Run with Docker¶

Three working ways to run the published kneo-serv Docker image. Pick the shape that matches what you're doing: quick local poke, real deployment, or one-shot CLI invocations.

For the reference of every supported deployment shape (including embedded ASGI), see deployment.md. For the guided zero-to-running PostgreSQL walkthrough, see tutorial_postgres_deployment.md.

All examples use ghcr.io/kneo-agent/kneo-serv:latest. Pin to a specific tag (:<version> or :<major>.<minor>) when you need reproducibility.

1. Quick kick-the-tires — single container, no auth, SQLite¶

The fastest way to see the service respond. No PostgreSQL, no API keys, no Compose — just one container with the SQLite-backed run state in an ephemeral volume.

docker run --rm -p 8000:8000 \
  -e KNEO_SERV_AUTH_ENABLED=false \
  ghcr.io/kneo-agent/kneo-serv:latest

In another terminal:

curl http://127.0.0.1:8000/healthz
# {"ok":true,"service":"kneo-serv-platform","version":"...",...}

curl http://127.0.0.1:8000/readyz
# {"ok":true,...,"checks":{"run_state_store":{"name":"run_state_store","ok":true},...}}

Run state lives at /app/.kneo/kneo_runs.sqlite inside the container and disappears when --rm cleans the container up. Don't use this shape for anything you want to keep around.

2. Production-ish — Compose stack with PostgreSQL sidecar¶

The operator-recommended path. Clone the repo to get compose.yaml and deploy/production.env.example:

git clone git@github.com:kneo-agent/kneo-serv.git
cd kneo-serv

cp deploy/production.env.example deploy/production.env
# Edit deploy/production.env — replace the `replace-*-token` API keys,
# set POSTGRES_PASSWORD, point providers at real keys, etc.

docker compose --env-file deploy/production.env pull
docker compose --env-file deploy/production.env up -d

compose.yaml defaults its image: to ghcr.io/kneo-agent/kneo-serv:latest. The build: block stays in place so contributors can run a local build with docker compose up --build. Auth is enabled by default in production.env.example; PostgreSQL provides durable run state and continuations.

Tear it down with:

docker compose --env-file deploy/production.env down -v

For the full walkthrough including the first authenticated request and how to migrate from a source build, see tutorial_postgres_deployment.md.

3. One-shot CLI usage inside the image¶

Spec validate / compile / one-shot run without keeping a service up. Useful for CI lanes, ad-hoc validation, and pre-flight checks against an artifact you don't want to install locally.

# Validate a local spec by mounting it
docker run --rm -v "$PWD:/work" --entrypoint kneo \
  ghcr.io/kneo-agent/kneo-serv:latest \
  spec validate /work/my_spec.yaml

# CLI help
docker run --rm --entrypoint kneo \
  ghcr.io/kneo-agent/kneo-serv:latest --help

--entrypoint kneo is required because the Dockerfile only sets CMD ["kneo", "service", "serve", ...], not ENTRYPOINT. Without the override, docker run treats the trailing args (spec validate ...) as the binary name and fails with exec: "spec": executable file not found in $PATH.

For the full CLI surface — local-state path, profile-backed service clients, run inspection, human-task resume — see cli.md and the generated cli_reference.md.