Compute
Kilimanjaro's compute plane runs every function in Firelock, the open-source sandbox maintained by Kilimanjaro. There is one tier, the sandbox. Each execution runs in a Firecracker microVM, and Firelock has two guests: Bun, for JavaScript and TypeScript, and Wasmtime, one base for everything that compiles to WASI. The guest is derived from the function's runtime label. One registry and one invocation surface cover every function.
1. Compute model
1.1 Sandbox characteristics
| Property | Sandbox |
|---|---|
| Runtime engine | Firecracker microVM, with a Bun or a Wasmtime guest |
| Code shape | A code bundle for Bun; a .wasm module for the WASI labels |
| Metering | Sandbox CPU-ms |
| Cold-start latency | 50–150ms (microVM boot) |
| Max execution time | 15min |
| Max memory | 4 GB |
| Network access | No network interface. All guest egress goes through one auditable vsock channel, where Keep's Warden layer evaluates each call |
| Filesystem | Read-only root; ephemeral scratch space, discarded on exit |
| Use case | Long-running jobs, external API calls, ML inference, database-intensive batch work |
The function's tier in the registry (_sys.functions.tier) is sandbox. Callers never choose how a function runs at invocation time: k9o.functions.invoke(name, ...) routes against the registry.
1.2 Supported runtimes
A function declares one of eight runtime labels. The label decides the guest, and no other value is accepted.
| Runtime label | Guest | Language |
|---|---|---|
bun | Bun | JavaScript and TypeScript |
rust | Wasmtime | Rust |
go | Wasmtime | Go |
tinygo | Wasmtime | TinyGo |
zig | Wasmtime | Zig |
assemblyscript | Wasmtime | AssemblyScript |
c | Wasmtime | C |
cpp | Wasmtime | C++ |
Any other runtime value is refused with 400 K9O_INVALID_FIELD_VALUE and context.field: "runtime", and nothing is written. A label and its artifact must match: a .wasm module under bun, or JavaScript source under rust, fails at registration with status: "error" and an error_detail. The platform builds no developer source, so install scripts, build.rs and go generate never run on its hosts.
1.3 Packaging
A deploy ships code in one of two packaging modes. bundle is the default.
| Mode | What you upload | Use it when |
|---|---|---|
bundle | A code bundle for bun, or a .wasm module for the WASI labels, run on a shared, pinned guest base | Your code needs nothing beyond the guest |
image | An OCI image archive (.tar, up to 256 MiB compressed) | You need native dependencies or OS packages |
Packaging is a choice about how the code ships, not a runtime label, so the eight labels don't change. An image carries any userland, and the supported languages remain the eight labels. Every image runs in its own microVM on Kilimanjaro's kernel, with Kilimanjaro's init as PID 1, a read-only root, and the one vsock egress channel. An image function has no warm pool, so each invocation is a cold boot, and you own the packages in your image.
Extensions ship a bundle or an image too, and either way the code is named by digest in a signed catalogue release.
1.4 Execution security
| Concern | How it is handled |
|---|---|
| Arbitrary code execution | Per-invocation microVM with hardware kernel isolation; WebAssembly guests add memory-safe semantics |
| Syscall abuse | Firecracker jailer and seccomp-BPF filtered syscalls; WASI capability subset for Wasmtime guests |
| Network egress | No network interface in the guest. Everything leaves through one auditable vsock channel, and Keep's Warden layer evaluates each call |
| Runaway execution | 15-minute hard timeout, OS-level kill |
| Trigger cascade | TRIGGER_LOOP_DETECTED at 5 recursive invocations |
Developers remain responsible for scoping the credentials and API keys their functions use.
2. Function registry
2.1 The registry is the single source of truth
The function registry lives in the project's system schema at _sys.functions. It is the canonical record for every project function regardless of origin — developer-deployed functions and extension-deployed functions share one registry. The source column records provenance ("developer" or "extension:<name>").
Why one registry: extension-deployed functions and developer-deployed functions are invoked identically via k9o.functions.invoke(name, ...). A single lookup point eliminates fragmentation. Extension-specific configuration (model selection, API keys, feature flags) lives in the extension's own schema; the function registration does not.
2.2 Status lifecycle
| Status | Meaning | Invocation behaviour |
|---|---|---|
deploying | Deployment pipeline in progress (artifact upload and preparation) | K9O_FUNCTION_NOT_READY (409) |
active | Function is healthy and invocable | Routes normally |
error | Last deployment failed; error_detail carries the failure description | K9O_FUNCTION_DEPLOYMENT_FAILED (422) |
retired | Function has been removed; row retained for audit; not invocable | K9O_FUNCTION_NOT_FOUND (404) |
Retired function names enter a 24-hour cooldown before the same name can be reused by a new deployment — this prevents silent substitution of a retired function.
2.3 Management endpoints
POST /@<projectSlug>/functions/artifacts — upload the artifact bytes; returns the content-addressed `artifactKey`
POST /@<projectSlug>/functions — deploy or redeploy
GET /@<projectSlug>/functions — list (cursor-paginated; filters: source, tier, status)
GET /@<projectSlug>/functions/<name> — function details
DELETE /@<projectSlug>/functions/<name> — retire (source: "developer" only)
Auth: PROJECT_ADMIN minimum on all four endpoints.
Deploy. Upload the artifact first (a code bundle or .wasm module, or an image archive in image packaging); the upload returns the artifactKey that the deploy call references. The k9o function deploy command does both steps. The platform registers the function with status: "deploying" and begins preparation asynchronously. Poll GET /functions/<name> for status: "active".
Create the client once
import { createClient, realtimeTopic } from "@k9o/core";
const k9o = createClient({
orgSlug: "acme",
projectSlug: "task-app",
apiKey: process.env.K9O_API_KEY,
});Compute · Multi-Runtime Serverless
import { readFile } from "node:fs/promises";
// Upload a tar image of the function, deploy it to the sandbox tier, then invoke it.
const tarBytes = await readFile("hello.tar");
const { data: artifact } = await k9o.functions.uploadArtifact(tarBytes, "tar");
await k9o.functions.deploy({ name: "hello", runtime: "bun", tier: "sandbox", artifactKey: artifact.artifactKey, version: "1" });
const { data } = await k9o.functions.invoke("hello", { name: "Alex" });
console.log(data);{ greeting: 'Hello, Alex' }- Deploy with
tier: "sandbox": a customer cannot deploy to the gateway tier. - The SDK types the invoke result as
unknown, so the example prints it as returned.
Delete. Transitions status to "retired" and starts the 24-hour name cooldown. Does not hard-delete the row — the audit trail is preserved. Returns K9O_ACCESS_DENIED with context.reason: "extension_managed" for extension-owned functions; their lifecycle is governed by the extension system.
2.4 CI/CD deployment
k9o function deploy is designed for scripted execution in CI/CD environments. In CI, a service token with PROJECT_ADMIN minimum is supplied via environment variables; no k9o login is needed:
export K9O_SERVICE_TOKEN=<service-token>
export K9O_ORG=<org-slug>
export K9O_PROJECT=<project-slug>
k9o function deploy --name process-upload --runtime bun --tier sandbox \
--version 1.2.0 --artifact ./process-upload.tar
The command uploads the artifact and then deploys it; pass --artifact-key instead of --artifact to deploy an artifact you have already uploaded. Deploy one function per command. The CLI is distributed as a standalone binary and a Docker image (k9o/cli:<version>).
Dependency scanning and vulnerability auditing are CI/CD-toolchain responsibilities upstream of k9o function deploy. The platform does not perform native static analysis on function artifacts.
3. Collection event triggers
3.1 Trigger registry
Triggers live in _sys.function_triggers and bind a function to a collection plus an event set:
| Field | Description |
|---|---|
function_name | Reference to a function in _sys.functions |
collection | The collection name to watch |
events | Subset of {"insert", "update", "delete", "upsert"} |
filter | Optional JSON-policy expression; when present, the function fires only on events whose record matches the expression |
enabled | When false, the trigger is registered but does not fire |
log_ok_invocations | When true, every successful invocation logs to _sys.function_trigger_log; default false (only errors log) |
One function may have multiple trigger rows (different collections or event sets). One collection may be targeted by multiple trigger rows.
3.2 Trigger management endpoints
POST /@<projectSlug>/functions/<name>/triggers — create
GET /@<projectSlug>/functions/<name>/triggers — list
PATCH /@<projectSlug>/functions/<name>/triggers/<trigger-id> — update (filter, enabled, events)
DELETE /@<projectSlug>/functions/<name>/triggers/<trigger-id> — delete
Auth: PROJECT_ADMIN minimum.
Create the client once
import { createClient, realtimeTopic } from "@k9o/core";
const k9o = createClient({
orgSlug: "acme",
projectSlug: "task-app",
apiKey: process.env.K9O_API_KEY,
});Compute · Scheduling
// A function on a timetable: every day at 09:00, New York time.
await k9o.schedules.create({
functionName: "daily-report",
scheduleExpression: "0 9 * * *", // five-field cron; an interval under 5 minutes can be refused
scheduleTimezone: "America/New_York",
catchupPolicy: "skip", // "skip" | "run_once" | "run_all"
});
const { data: schedules } = await k9o.schedules.list({ functionName: "daily-report" });
console.log(schedules.map((s) => `${s.scheduleExpression} ${s.scheduleTimezone}`));[ '0 9 * * * America/New_York' ]- A personal access token answers 403
K9O_RBAC_DENY(cannot own a schedule). Create schedules from a signed-in session.
4. SDK invocation
4.1 k9o.functions.invoke
POST /@<projectSlug>/functions/<name>/invoke
Two modes:
| Mode | Behaviour | Response shape |
|---|---|---|
| Synchronous (default) | Waits for the function to complete and returns the result | 200 OK with { data, meta: { functionName, version, durationMs, invocationId } } |
Fire-and-forget (background: true) | Returns immediately without waiting | 202 Accepted with { data: { invocationId } } |
4.2 Routing
The API gateway resolves the function name against the registry for the active project and routes the call to the Firelock sandbox: synchronous or async per the background flag. MicroVMs are pre-warmed for active bundle functions (cold start ≤ 150ms).
Callers don't need to know how a function runs; the registry handles routing.
4.3 Invocation error codes
| Code | Status | Condition |
|---|---|---|
K9O_FUNCTION_NOT_FOUND | 404 | Function name does not exist or is retired |
K9O_FUNCTION_NOT_READY | 409 | Function exists but status: "deploying" |
K9O_FUNCTION_DEPLOYMENT_FAILED | 422 | Function status: "error" — last deployment failed |
K9O_FUNCTION_TIMEOUT | 504 | Function exceeded the maximum execution time |
K9O_FUNCTION_MEMORY_EXCEEDED | 503 | Function exceeded the memory limit |
K9O_FUNCTION_RUNTIME_ERROR | 422 | Function threw an unhandled exception; context.exitCode and context.stderr included |
5. Billing
5.1 Sandbox — CPU-ms
Everything that runs in the sandbox (Firecracker microVM) bills in sandbox CPU-ms, CPU milliseconds of active execution: functions, extensions, workflows and Warden. Usage is drawn from the monthly allowance that comes with your capacity packs (100M CPU-ms per pack) and then, with Headroom on, billed per million CPU-ms; without Headroom it throttles. Invocations are counted and reported but never priced per request. See Billing guide §7.
5.2 Progress reporting (the retired Waypoint API)
The k9o.functions.waypoint() API — a manual, per-emission progress-and-billing call — has been retired; it no longer exists, and there is no separate "waypoints" billing dimension for function progress. Long-running work is metered only on the standard compute dimension, CPU-ms in the sandbox.
"Governed Operation" — the metered unit of governed agent actions crossing the Keep enforcement boundary — is a distinct concept from this retired function-progress waypoint; see Keep → Billing.
6. Extension-deployed functions
Extensions can deploy their own functions as part of their install lifecycle. Extension-owned functions are registered in the same _sys.functions registry with source: "extension:<name>" and follow the same deploying → active → error → retired status lifecycle as developer-deployed functions. Extension uninstall hard-deletes the extension's functions; developer-deployed functions soft-retire instead.
Extension-owned functions cannot be deleted via the developer DELETE endpoint — that returns K9O_ACCESS_DENIED with context.reason: "extension_managed". Lifecycle management for extension functions is the responsibility of the extension framework.
6.1 Trailblazer-class extensions
Four Trailblazer-class extensions ship with the platform as canonical reference implementations of the extensions framework:
| Trailblazer | Source label | Purpose |
|---|---|---|
| Paperless | extension:paperless | AI-enabled team workspace; chat with agents, AI-generated workflows, rich data capture |
| Context | extension:context | Semantic-intelligence + embedding pipeline |
| Lookout | extension:lookout | Real-time observability + analytics surfaces |
| Gate Studio | extension:gate-studio | Visual command centre for authoring Gate (Identity-Aware Kernel) login pages, Maker-Checker registration flows, jurisdictional ingress policies, branded UI, and white-labelling |
Each Trailblazer-class extension is documented on its own page under /extensions.
7. Models and the ai calls
Compute also serves language models. compute.llms lists the models available to your organisation and streams a model's output; ai.generate and ai.embed are the one-call forms for text generation and embeddings.
7.1 Embeddings
ai.embed turns text into a vector. Embeddings are 768 dimensions (nomic-embed-text-v1.5).
Create the client once
import { createClient, realtimeTopic } from "@k9o/core";
const k9o = createClient({
orgSlug: "acme",
projectSlug: "task-app",
apiKey: process.env.K9O_API_KEY,
});Pulse · Compute: ask a model, then call a function
Setup
// Which models can this project call?
const { data: models } = await k9o.compute.llms.list();
const model = models.find((m) => m.id === "mistral-7b") ?? models[0]!;
const prompt = "In one sentence, what does a customer want when they ask 'Where is my order?'";console.log(models.map((m) => m.id).join(", "));phi-3-mini, mistral-7b, mistral-8x7b, llama-3-8b, llama-3-70b, claude-3-5-sonnet, gpt-4o, gpt-4o-mini, ...7.2 Generate and stream
ai.generate(prompt, options) returns the model's answer in content, with token counts in usage and the reason it stopped in finishReason. compute.llms.invokeStream returns the same generation as chunks, each carrying the next piece of text in choices[0].delta.content; the last chunk can carry usage and no choices, so read choices defensively. In the example, context stands for the passages you retrieved for the question.
Create the client once
import { createClient, realtimeTopic } from "@k9o/core";
const k9o = createClient({
orgSlug: "acme",
projectSlug: "task-app",
apiKey: process.env.K9O_API_KEY,
});Compute · Agentic Orchestration: the LLM and `ai.*` APIs
Setup
// Pick a model
const { data: models } = await k9o.compute.llms.list();
const model = models.find((m) => m.id === "mistral-7b") ?? models[0]!;
// Retrieve context: embed the question, find its nearest support articles.
const question = "Where is order #123?";
const { data: embedded } = await k9o.ai.embed({ input: question });
const { data: found } = await k9o.vectors.nearest("_support_articles", {
queryVector: embedded.embeddings[0]!,
topK: 4,
minScore: 0.3,
filters: { "metadata.language": "en" },
});
const context = found.results.map((r) => r.text).join("\n---\n");
const prompt = `Answer using only this context.\n\n${context}\n\nQuestion: ${question}`;// Generate an answer grounded in that context.
const { data: answer } = await k9o.ai.generate(prompt, {
model: model.id,
maxTokens: 400,
temperature: 0.2,
usageType: "support-agent",
});
console.log(answer.content);
console.log(`${answer.usage.totalTokens} tokens, finished: ${answer.finishReason}`);
// Record the run to a stream for audit and replay.
await k9o.streams.publish("agent-runs", {
question,
model: model.id,
tokens: answer.usage.totalTokens,
});Order #123 shipped on Monday and is due Thursday.
212 tokens, finished: stop- Without
model,ai.generateuses the organisation's default model and answers 400 when there is none. Embeddings are 768 dimensions (nomic-embed-text-v1.5). - Models served by an outside provider answer 501 until a tenant key is configured.
- Without
model,ai.generateuses the organisation's default model and answers400when there is none. - A model served by an outside provider answers
501until a tenant key for that provider is configured. - A generation can take tens of seconds on a model that has not been used recently, so allow a generous client timeout.
7.3 Messaging
Messaging between functions, agents and services runs on streams: a producer calls streams.publish and a consumer loops over streams.subscribe.
Create the client once
import { createClient, realtimeTopic } from "@k9o/core";
const k9o = createClient({
orgSlug: "acme",
projectSlug: "task-app",
apiKey: process.env.K9O_API_KEY,
});Compute · Intelligent Messaging & Pub/Sub
// A producer publishes; any number of consumers subscribe, in order, from any point.
await k9o.streams.publish("orders", { id: 1, total: 42 }, { subject: "eu.new" });
for await (const event of k9o.streams.subscribe("orders", { fromSequence: 0 })) {
console.log(event.sequence, JSON.stringify(event.data));
}1 {"id":1,"total":42}The generate example above records each run to a stream; the calls, ordering and replay are in Data §5.5.