Running the Runtime

kx serve starts the agentic runtime as a server on your machine. It is the thing your apps, your agents, the CLI, and the web console all talk to. One command starts all of it.

Auth is deny-all by default

The runtime answers nobody until you tell it who to answer. A bare kx serve does not start an open server — it stops before binding anything and exits with status 2, because starting an unauthenticated server would be the wrong default.

Start it with no auth flags at all and it prints the usage text and this line on standard error:

kx: kx serve refuses unauthenticated access. Re-run with --dev-allow-local (loopback-only dev access), or --auth-token <token>=<party> / --auth-token-file <path> for token auth.

You have two ways to open it. Pick exactly one — the loopback dev posture and configured tokens are mutually exclusive, and passing both is a config error.

# Local development: accept callers from this machine only.
kx serve --dev-allow-local

# Token auth: a bearer token maps to a named party.
kx serve --auth-token-file ~/.kortecx/tokens.txt

# You start the server from a terminal; code connects to it.
from kortecx import KxClient

with KxClient("http://127.0.0.1:50151") as kx:
    result = kx.invoke("kx/recipes/echo", {"topic": "hello"}, wait=True)
    print(result.state)
    # The demo recipe returns binary bytes, so result.text is None here.
    print((result.bytes or b"")[:32])

// You start the server from a terminal; code connects to it.
import { KxClient, type Result } from "@kortecx/sdk";

const kx = new KxClient("http://127.0.0.1:50151");
const result = (await kx.invoke(
  "kx/recipes/echo",
  { topic: "hello" },
  { wait: true },
)) as Result;
console.log(result.state, result.instanceId);
kx.close();

What it opens

One kx serve opens up to three surfaces. Every resolved path and endpoint is written to a startup log line on standard error (tracing is on at info by default), so you can read back exactly what resolved where.

The event stream uses the same auth posture as the gRPC endpoint: an upgrade that carries no accepted token is rejected before any stream opens.

Where the console is present it binds loopback only — a non-loopback --console-listen is refused. Open http://127.0.0.1:8888 in a browser on the same machine and point it at http://127.0.0.1:50151. If you use a bearer token, it is held only in the page's memory and is never written to disk.

Turn the console off with --no-console, or move it to another loopback port with --console-listen <addr:port>.

Starting it, end to end

kx serve --dev-allow-local

kx health
kx info

kx invoke kx/recipes/echo --args '{"topic":"durable agents"}' --wait

kx events --instance <instance-id> --follow

Every flag

These are the flags kx serve accepts.

Auth posture — one of these is required

--dev-allow-local and the token flags cannot be combined. Prefer --auth-token-file: a token passed on the command line is visible to anyone who can list processes on the machine.

Addresses

Browsers and transport

--cors-origin takes a full origin — https://dashboard.example.com, scheme and host and port. It is repeatable and it never accepts a wildcard. When the console is running, the runtime adds the console's own bound loopback origins (http://127.0.0.1:<port> and http://localhost:<port>, at whatever port it actually bound) to the allowlist automatically, so you do not need a --cors-origin for it — including when you moved it with --console-listen.

TLS covers the gRPC listener. The WebSocket bridge and the web console are plaintext — if a remote browser needs the event stream, put a TLS proxy in front.

Storage

Work and observation

--workers must be a positive integer and is clamped to a built-in maximum. Start at 1 and raise it if your runs have several independent Pure, IO or tool steps ready at the same time.

The audit log is written off the truth path. It records join keys only — never payload bytes, never model output, never secrets — and turning it on never changes a run's committed facts or its product digest.

Environment variables

KX_DATA_DIR=/data/kortecx kx serve --dev-allow-local

KX_SERVE_MEMORY is the older spelling of the flag and still works; KX_FLAG_SERVE_MEMORY is the current name and wins if both are set.

Durable memory is gated. It needs KX_SERVE_MEMORY=1, a served model, and an hnsw build — see Memory. Datasets require an hnsw build too.

A server two machines can reach

If a second machine or a browser on another host needs to reach the runtime, three things change together.

# ~/.kortecx/tokens.txt
a-long-random-string=alice
another-long-random-string=ci-runner

kx serve \
  --auth-token-file ~/.kortecx/tokens.txt \
  --listen 0.0.0.0:50151 \
  --tls-cert /etc/kortecx/cert.pem \
  --tls-key /etc/kortecx/key.pem

kx serve \
  --auth-token-file ~/.kortecx/tokens.txt \
  --listen 0.0.0.0:50151 \
  --tls-cert /etc/kortecx/cert.pem \
  --tls-key /etc/kortecx/key.pem \
  --cors-origin https://dashboard.example.com

Clients

Every client command — kx invoke, kx events, kx projection, and the rest — takes the same connection flags:

kx invoke kx/recipes/echo --args '{"topic":"hello"}' --wait \
  --endpoint https://runtime.example.com:50151 --token-file ~/.kortecx/my-token

What this is not

The runtime is single-system by default. One kx serve is one machine: its journal, its content store, its workers. Running across several nodes is on the roadmap, not in the box today. The server runs for exactly as long as you leave it running — it does not stop or start itself, and it does not add or remove capacity on its own.