Hosted mode¶

Hosted mode is the $PORT convention used by platforms such as Cloud Run, Render, Fly.io, Railway, App Engine, and Heroku-style runtimes.

When no --listen flag and no config listen are set, kata daemon start --foreground binds 0.0.0.0:$PORT if PORT is in the environment. Plain kata daemon start is for local operator use: it starts a background daemon and returns after startup is confirmed.

Auto-started local child daemons set KATA_AUTOSTART=1, so a stray PORT on a developer machine does not flip implicit local daemons onto wildcard TCP.

Required environment¶

Set:

KATA_AUTH_TOKEN=<token>
KATA_TRUST_PRIVATE_NETWORK=1
KATA_HOME=/writable/path

Without both KATA_AUTH_TOKEN and KATA_TRUST_PRIVATE_NETWORK=1, the daemon refuses the non-loopback bind. Hosted platforms commonly terminate TLS upstream, so the operator must explicitly assert trust in the container network path.

Browser origin and proxying¶

Set the exact external HTTPS origin when the platform terminates TLS:

[web]
public_origin = "https://daemon.example"

The origin is a security input, not display metadata. Kata validates Host and mutation Origin against it and never trusts forwarded headers to discover it. The platform must send the SPA, hashed assets, browser-session routes, data API, and /api/v1/events/stream to the same daemon. Disable response buffering for the event stream so authenticated invalidations flush immediately.

Opening a hosted deep link without browser authority shows token login and returns to that path after exchange. The browser retains only its paired cookie/session-header credentials and CSRF value; a fresh tab needs its own login because cookie-only recovery is intentionally unavailable.

KATA_HOME must point at writable storage. Local container disk is often ephemeral, so data does not survive instance recycling unless KATA_HOME is backed by a mounted volume or shared storage.

Health probes¶

Use either endpoint for liveness or readiness:

GET /api/v1/health
GET /api/v1/ping

Both are unauthenticated.

Shutdown¶

The daemon handles SIGTERM gracefully, with up to 10 seconds for in-flight requests.

Single-instance assumption¶

kata assumes one daemon per database. Deploying multiple hosted instances without shared storage gives each instance its own state. Deploying multiple instances against one SQLite database is not a supported high-availability shape.

For team workflows that need one central state store, run one daemon against one database and put platform routing in front of that process.