Build Your Own Extension
Extensions are how you ship a complete surface on top of Kilimanjaro — Console UI, runtime API, optional background logic — consuming the same auth, RBAC, and data primitives as any core platform feature. The four Trailblazer-class extensions (Paperless, Context, Lookout, Gate Studio) are themselves extensions built on this framework; everything they have access to, you have access to.
This page is the developer guide. The full framework contract is on the Extensions API reference.
1. What an extension is
An extension is a versioned, slug-identified resource that ships three things:
- A manifest — declarative JSON document binding identity, permissions, surfaces, hooks, and version.
- A bundle — static assets under a
staticFilesdirectory (Console iframe bundles + brand assets) served from the platform's user-content host (https://<label>-cdn-<rgn>.<usercontent-domain>/extensions/<slug>/<version>/...), plus the runtime code serving any declaredsurfaces.runtime_apiandbackground_logic.functions[]. - Runtime handlers — exported functions in your bundle that the platform's API class gateway (
<orgSlug>.api.k9o.io/@<projectSlug>/extensions/<slug>/<path>) dispatches to. The gateway terminates TLS, verifies the plugin token, checks the per-routepermission_scope, and only then invokes your handler — there is no separate HTTPS server you operate.
The extension runs outside the platform's trust boundary: it authenticates back into the platform with its own scoped plugin token, granted only the permissions the manifest declares and the project admin authorises at enable time. There is no "all-bypass" elevation path. The same per-project SQL schema isolation that bounds core platform features bounds your extension's data; cross-schema reads and writes go through the gateway API.
2. Authoring the manifest
The manifest is the source of truth for everything the platform knows about your extension. It validates at three moments: registration, version update, and project enable.
2.1 Minimum viable manifest
A function-only extension that mirrors every document write to your SIEM looks like:
{
"manifest_version": 1,
"slug": "audit-mirror",
"name": "Audit Mirror",
"version": "0.1.0",
"publisher": { "name": "Your Org", "url": "https://yourorg.example" },
"description": "Mirrors document writes to your SIEM in real time.",
"permissions": [
{ "domain": "documents", "action": "read", "qualifier": "*" },
{ "domain": "webhooks", "action": "subscribe", "qualifier": ["document.created", "document.updated", "document.deleted"] }
],
"surfaces": {
"console": null,
"runtime_api": { "function": "mirror-to-siem" },
"background_logic": {
"functions": [
{ "name": "mirror-to-siem", "runtime": "bun", "tier": "sandbox", "entry_point": "./dist/mirror.js" }
]
}
},
"schema": null,
"hooks": {
"enable": {},
"purge": {}
}
}
2.2 Common surface shapes
| Shape | Use when | Required surfaces |
|---|---|---|
| Console-only extension | You're adding a Console UI to an existing platform capability (e.g., a visualisation surface). | console non-null; runtime_api null; background_logic null. Iframe bundles live under the top-level staticFiles directory at <staticFiles>/iframe/<surface-name>/. |
| API-only extension | You're exposing programmatic routes (e.g., a webhook bridge, a transform-and-store pipeline). | runtime_api declares a mount prefix and a bundled OpenAPI spec; the extension runtime serves the routes the spec documents. |
| Function-only extension | You're running event-driven code (document.created triggers, scheduled jobs, etc.) without a UI. | background_logic.functions[] non-null with one or more function descriptors |
| Full-surface extension | All three (Console UI + dynamic routes + functions). The four Trailblazer-class extensions are this shape. | All three sub-objects non-null |
At least one must be non-null — a no-surface extension is rejected at manifest validation.
2.3 Permissions
Permissions are (domain, action, qualifier) triples bound by the closed vocabulary in §2.2 of the framework spec. Some discipline:
- Ask for the narrowest qualifier that works. A
"*"qualifier ondocuments/writegrants writes to every collection the project ever creates; a slug list (["forms-submissions", "templates"]) bounds the grant to the collections you actually touch. - The grant binds at enable time and is immutable to your extension. If you ship a version 1.1.0 that adds a permission, every project running version 1.0.x sees a re-authorisation prompt before the upgrade takes effect. Plan permission additions deliberately.
- No "all-bypass" pattern exists. Sovereign Control / Private Perimeter customers cannot grant an unscoped service token even to a Kilimanjaro extension; your extension is the same.
2.4 Schema
If your extension stores its own data, declare it:
"schema": {
"tables": ["records", "subscriptions_cache"],
"migrations": "./dist/migrations/"
}
The platform provisions k9o_<proj_id>_ext_<schema_slug> on first enable and runs your migrations forward; on disable it preserves the schema; on purge it drops it. The plugin token has DDL within this schema only (no DDL anywhere else) — a hard guarantee at the Postgres-role-privilege level.
Migration files follow the platform's standard naming: <timestamp>_<description>.up.sql and matching .down.sql. Failed migrations roll back atomically.
2.5 Hooks
The five lifecycle hooks are how the platform tells your extension about state changes. The platform delivers each one as a dispatcher frame to the host function named in surfaces.runtime_api.function, with context.kind set to "hook" and context.hookName set to the event. That function must have a sandbox entry of the same name in background_logic.functions[]; a manifest that declares hooks without surfaces.runtime_api.function is refused with K9O_EXTENSION_MANIFEST_INVALID.
| Hook | Synchronous? | Use for |
|---|---|---|
enable | Yes | First-enable bootstrapping. If the hook fails the enable aborts and rolls back. |
configure | Yes | Version-update reconfiguration. Same abort semantics. |
activate | No | Wake-from-disabled. Async — your handler should be idempotent. |
deactivate | No | Disable preparation. Async — flush state if you can; the plugin token is revoked shortly after. |
purge | No | Purge cleanup. 30-second grace before the plugin token is revoked. |
All hooks are optional. Event subscriptions (via permissions[] with domain: "webhooks") follow the standard webhook delivery contract per SIEM forwarding mechanics. The platform delivers hooks at-least-once, so make every hook handler idempotent.
3. Local development
The extension framework supports a local-development loop that runs your extension against a local Kilimanjaro instance via the .localhost TLD pattern. The pattern:
- Run a local Kilimanjaro instance (the
K9O_ROUTING_MODE: subdomaindefault plus the.localhostTLD handles routing without DNS configuration). - Author your
manifest.json+ bundle locally; the manifest'sstaticFilesdirectory holds your Console iframe bundle + brand assets. - Register the dev-mode extension against the local instance; the local gateway publishes your
staticFilesto its user-content host and mounts yourruntime_apiprefix on its API class. - Enable the dev extension on a local project; iterate. The same plugin-token and permission-grant contracts apply locally as in production.
A full local-development tooling surface (@k9o/extension-dev package + the dev-mode registration endpoint) is being staged for early-adopter access; until it lands, the manual local-instance pattern is the supported flow.
4. Publishing and curation
Every extension belongs to one of three classes, set by integration depth — see Extensions API reference → Extension classes for the canonical taxonomy. Class is not a quality tier or a partner tier, and it is not assigned by the outcome of curation review.
4.1 The three classes from a builder's perspective
| Class | What it is | What it means for you |
|---|---|---|
| Trailblazer | Flagship functionality that the Console is aware of and is noticeably incomplete without | Reserved for the four flagship extensions (Paperless, Context, Lookout, Gate Studio) |
| Anchor | An activation wrapper over in-built platform functionality | Reserved for Data Bridges and Event Bridges. A Data Bridge rides the platform's change-data-capture substrate, bindings store with approvals, databridge permission grants and erasure handshake; an Event Bridge rides the platform transport with extension attribution and carries no extension code |
| Circuit | Every other extension | Where integrations, utilities and capability surfaces sit; standard curation review |
An extension is not promoted between classes by review outcome. Being featured in the Hub is independent of class.
4.2 What the curation programme reviews
Every submitted extension passes through review against four focus areas, regardless of class:
- Manifest correctness — schema validity, permission scoping, surface declaration coherence,
runtime_apishape (valid OpenAPIspec),staticFilesdirectory layout. - Plugin token usage — does the runtime present its plugin token on platform API calls, handle re-authorisation prompts?
- Trust boundary — does the extension respect the per-project schema isolation? Does it leak data across projects? Does it call external hosts outside its declared
fetch_external_url:<host>capability tokens? - Customer-facing surface quality — does the Console UI hold up to the platform's design conventions; do the routes behind your
runtime_apiprefix behave correctly under the platform-mounted dispatch; do the lifecycle hooks behave under retry?
Anchor-class submissions additionally undergo brand-partnership coordination. Class assignment is published in the extension's listing once review completes.
To register interest in the programme, contact support.
5. Patterns and constraints
5.1 The trust boundary is binding
Extensions run outside the trust boundary. Concretely:
- The plugin token is the only authentication path into the platform from your extension. There is no shared-secret elevation, no project-admin impersonation, no debug-mode bypass.
- The manifest permission grant is checked on every API call by the gateway. A grant for
documents/read/*does not let your extension write; the JSON policy on a specific row can still deny read. - The extension's own per-project schema is its only direct SQL surface. Cross-schema reads and writes go through the gateway API.
- The Console iframe is sandboxed; the extension does not have direct DOM or React-state access to the Console.
5.2 Idempotency is required
Every platform-to-extension delivery is at-least-once. Build every handler — hooks, webhook subscriptions, function triggers — to dedupe on the relevant event ID and produce the same result on repeated invocation. Webhook events carry their own eventId.
5.3 Permission grants are immutable within a version
A version 1.0.0 enable binds the v1.0.0 permission set. Version 1.0.1 that does not add permissions auto-applies; version 1.1.0 that adds a permission triggers re-authorisation. Plan permission additions deliberately and bundle them into minor-version bumps rather than scattering them across patches.
5.4 Runtime hosting tiers
The platform hosts your extension's running process via the surfaces.background_logic.runtime_tier manifest field. Both tiers are first-class:
runtime_tier: "wasm"— Bun + WebAssembly sandbox; the platform executes your code under a sandbox compute envelope. Suitable for TypeScript / JavaScript / Rust-WASM-targeted extensions.runtime_tier: "container"— Firecracker microVM hosting; the platform executes your container image at deploy time (OCI→ext4 conversion + jailer-wrapper). Required when your extension targets a language outside the WASM family (Python / Java / Kotlin / .NET / Swift / PHP / Ruby / Go-native / Rust-native / Zig-native).runtime_tier: null(or absent) — the extension's backend runs on your own infrastructure (legacy proxy path). Suitable when you already have an off-platform service you're wrapping.
Both wasm and container tiers compose against the same per-extension sandbox-isolation contract — the gateway forwards requests under your surfaces.runtime_api prefix to your runtime regardless of tier; choice is a deployment decision, not a contract one.
6. See also
- Extensions API reference — the full framework contract.
- Paperless — AI-enabled team workspace Trailblazer-class extension; reference implementation for a full-surface extension.
- Context — semantic-intelligence Trailblazer-class extension.
- Lookout — dashboarding Trailblazer-class extension.
- Gate Studio — visual Gate authoring Trailblazer-class extension.
- API → Compute — function registry that
background_logic.functions[]deploys against. - API → Security — RBAC + audit-log family for the extension lifecycle.
- API → Control — JSON-policy evaluation layered on the manifest grant.