Production Notes and Limitations

The home page and the about page both point here. That is deliberate. This page is where the ambition gets qualified, and nothing on it is softened.

The agentic runtime is in early development, pre-1.0. We make no claim about its readiness for work that matters to someone else, and you should not make one on our behalf.

What follows is the whole list. Read it before you put the runtime near anything that matters. If a limit below is a dealbreaker for you, that is the page working as intended.

The shape of the thing

The runtime is one binary you run on one machine. It records every step of an agent's work to an append-only log on local disk, so a crash cannot make a world-touching step happen twice. That durability property is real, it is demonstrable, and it is what we stand behind. Almost everything else on this page is a boundary around it.

Pin a release tag for anything you keep. Interfaces change before 1.0.

Scale

Single-system by default. One journal writer, one machine. There is no multi-node deployment today — running the runtime across several machines is roadmap work, not a flag you can pass. See Roadmap.

No multi-tenant isolation. Auth is a bearer token mapped to a party. Parties are not isolated tenants: there is no boundary that stops one party's configuration and one machine's resources from being shared with another. Run one instance per trust boundary, and treat the machine as the boundary.

Nothing manages capacity for you. The server runs until you stop it. It does not add machines under load, and it does not stand itself down when nothing is running.

Auth and the network surface

Auth is deny-all by default. Started with no auth posture, the server refuses to run: it fails fast with a usage error and a hint rather than opening an unauthenticated port. You must choose one of two postures:

# Local development: accept callers on the loopback interface only.
kx serve --dev-allow-local

# Or map a bearer token to a party (repeatable; --auth-token-file reads a file).
kx serve --auth-token my-token=alice

The token and party above are placeholders — choose your own. Listeners bind loopback by default, and the web console will only bind a loopback address at all. Browser access is deny-by-default: no origin can call the runtime from a page until you name it with --cors-origin, and a wildcard origin is refused.

Transport is partly plaintext. In-binary TLS covers the gRPC listener (--tls-cert / --tls-key). The live-event WebSocket bridge and the web console are loopback plaintext — there is no TLS for them in the binary. Put a TLS proxy in front if a remote browser needs to reach them.

kx serve --tls-cert cert.pem --tls-key key.pem --auth-token my-token=alice

A bearer token in a browser is visible to page JavaScript. Tokens are never persisted beyond memory by the console or the SDKs, which is not the same as safe. Use short-lived, narrowly-scoped tokens over https:// for anything that is not a trusted first-party dashboard.

The accepted timing side-channel

This one is documented rather than fixed, and you should know it by name.

Bearer-token comparison is not constant-time. The single-node local gateway compares your auth token with an ordinary equality check. In principle, an attacker who can measure response timing precisely can learn the token one byte at a time. This limitation was accepted for a loopback / trusted-single-node deployment and written down instead of quietly shipped; the constant-time compare and token rotation belong to the managed cloud auth layer, which is not this.

If your deployment is not loopback and not single-tenant-trusted, this is a real risk to you and you should treat the token as weak.

Local inference

Local inference means running a model on your own hardware — no API keys, no egress. There are two ways to do it, and only one of them is in the default build.

Out of the box, the prebuilt binary talks to a separate local model daemon that you install and run yourself. It needs no C++ toolchain and no Node. If you build from source, that path is a cargo feature:

cargo install --path crates/kx-cli --features serve-engine,hnsw

In-process inference — the model runs inside the runtime, with no separate daemon — is not in the default build. It requires a build with a C++ toolchain installed (CMake and clang/libclang), plus a compatible model file on disk:

cargo install --path crates/kx-cli --features inference,hnsw

One model, single-stream decoding per server. Work is generated one stream at a time. Details in Local inference.

Memory and datasets need opt-in builds and flags

Neither is on by default. Both are gated, and the gates are load-bearing.

Durable memory — an agent remembering a fact across separate runs — needs KX_SERVE_MEMORY=1, a served model, and an hnsw build. Without all three, the memory calls are not present at all:

KX_SERVE_MEMORY=1 kx serve --dev-allow-local

Datasets — the document corpora agents search to ground their answers — require an hnsw build:

cargo install --path crates/kx-cli --features hnsw

The prebuilt binary is built with hnsw, so it includes datasets. A plain cargo install from source, with no features named, does not. See Memory and Datasets.

Hosted web apps are a non-default, local-only feature

An App can carry a small web front end that the runtime builds and runs for you. Read this paragraph carefully, because it is the most misread capability we ship.

• It is a non-default cargo feature (hosted-apps). In a build without it, the four hosted-app calls return "unimplemented". The prebuilt binary is not built with that feature.
• The dev server runs on loopback, at http://127.0.0.1:<port>/. That address is reachable from your machine and nowhere else.
• There is no reverse proxy. Nothing fronts it, terminates TLS for it, or gives it a public address.
• There is no sandbox. The supervisor is an ordinary child process on your host. It installs JavaScript dependencies and runs a dev server with your user's permissions. Treat running someone else's hosted app exactly as you would treat running their code, because that is what it is.
• It is single-user and local. A public URL, a proxy, and tenant isolation are not part of this.

There is no mechanism here for making an App reachable by other people — no public address, and nothing outside your own machine can open it. Hosted apps says the same thing at greater length.

What an exported App proves — and what it does not

You can package an agent as a portable bundle and hand it to someone:

kx app export apps/local/my-agent --bundle my-agent.appbundle

kx app import my-agent.appbundle

On import, the bundle records a source_digest: the digest of the app it came from.

That is a lineage hint, not a signature. There is no signing in the local runtime. source_digest tells you what an app claims to have been derived from. It does not prove who authored it, does not prove the bytes were not altered, and does not make the sender trustworthy. Read a bundle before you run it.

What the design does give you: an App carries no authority. Importing one grants it nothing. Every capability it wants is re-resolved against your grants at run time, and connections and secrets never travel inside a bundle — you re-register your own by name. A hostile App still cannot silently acquire powers you did not give it. See Sharing an app.

Things that do not exist

Stated plainly, because their absence is easy to assume away.

• One app cannot call another app. There is no invocation, chaining, or message-passing between two Apps at any layer. Agents coordinate inside one app — a blueprint DAG, or a multi-agent pattern run from the CLI:

  kx swarm --pattern supervisor --planner "Plan the work" "Do A" "Do B"

  If your design needs App A to trigger App B, the runtime has no answer for you today. See Workflows.

• No multi-node deployment.

• No OpenTelemetry export. What exists is an opt-in Prometheus /metrics endpoint, off unless you ask for it:

  kx serve --dev-allow-local --metrics-listen 127.0.0.1:9090

• No service commitment and no compliance certification. Nobody is on call for your instance, nothing is promised about availability, and no audit or certification has been performed. You operate it.

• kx tools register alone does not give you a working integration. It records a tool in the registry. Actually dialing an external host is what kx connections does — that is the local path that really calls out.

Observability and cost are display-only

Everything in this section is audit and display material. None of it is truth, and none of it feeds a run's identity or its digest.

• Metrics: the opt-in Prometheus endpoint above.
• Telemetry: per-step execution records and a per-model token rollup.
• Cost: a local spend estimate at rates you configure, with a ceiling — not a bill. It is built from what the local runtime measures locally, not from everything a provider would charge you for.
• Alerts: terminal failures land in an inbox instead of vanishing. That is an inbox you read, not a pager that finds you.
• Audit log: an off-the-truth-path JSONL record of the run lifecycle, join-keys only, never payloads or secrets, enabled by --audit-log.

More in Observability and Cost.

What we do stand behind

A complete list of limits is only useful next to a complete list of what holds.

• Exactly-once execution across crashes. A step that touched the world is re-read on recovery, never re-run. You can demonstrate it yourself: run the canonical workflow, crash it mid-commit, replay, and compare digests. The Quickstart walks through it, and the same script runs in CI, so these docs cannot silently drift from the code.
• The model proposes; the runtime enforces. A model may suggest a tool call or an action. Only the runtime decides whether it happens, and it decides by exact equality — never by a similarity score.
• Identity is server-derived. No client, SDK, or model constructs a run identity or asserts who it is. Your party comes from your token.
• Closed by default. Auth, listeners, and browser origins all start shut.

Reading this page as a decision