Deploy with Docker and Kubernetes

10xgraph build generates a production-ready Dockerfile and .dockerignore for your agent, and with flags also a docker-compose.yml and a k8s.yaml manifest. The images run Gunicorn with Uvicorn workers in MODE=production. This guide covers building, configuring, and shipping your deployment with a release checklist.

Which flags does build take?

Without --force, build stops if the Dockerfile exists. It skips an existing .dockerignore, but errors on an existing docker-compose.yml or k8s.yaml.

What files does it generate?

The Dockerfile sets MODE=production, IS_DEBUG=false and WEB_CONCURRENCY=2, installs gunicorn and uvicorn, removes the CLI-only files from the installed package, copies your project, drops to a non-root appuser, and defines a HEALTHCHECK that calls /ping. Its CMD runs tenxgraph_api.src.app.main:app under Gunicorn with --graceful-timeout 600 and --timeout 660.

Does the image ship the CLI and the config editor?

No. 10xgraph-api is one package with two halves: the API server, and the CLI you use on your machine (init, build, eval, the 10xgraph config browser editor, project templates and the bundled agent skill). Seeing CLI code and HTML/JS in the package can look like extra attack surface on a production server. It is not, for two reasons.

The server never touches the CLI half. It imports one CLI file, tenxgraph_api/cli/constants.py, for the version string. No route serves the editor’s HTML or JS, and the editor itself only runs when you type 10xgraph config. Even then it listens on 127.0.0.1 and needs a random per-session token.

The generated image removes it anyway. Right after installing dependencies, the Dockerfile deletes the templates and the config editor from the installed package:

# Strip CLI-only assets the server never loads: project scaffolds, the bundled
# agent skill, and the local config editor (HTML/JS). Only the server code and
# its dependencies stay in the image.
RUN python -I -c "import importlib.util, pathlib, shutil; spec = importlib.util.find_spec('tenxgraph_api'); cli = pathlib.Path(spec.origin).parent / 'cli' if spec and spec.origin else None; [shutil.rmtree(cli / d, ignore_errors=True) for d in ('templates', 'config_editor') if cli]"

The CLI’s small Python modules stay, so 10xgraph version and 10xgraph audit still work inside a running container for debugging.

The generated .dockerignore does the same for your project: tests/, evals/ and installed skill folders (.claude/, .agents/, .github/) are not copied into the image, along with .env files, caches and virtual environments.

You can check a built image yourself:

docker build -t my-agent .
docker run --rm my-agent python -c "import pathlib, tenxgraph_api; print(sorted(p.name for p in (pathlib.Path(tenxgraph_api.__file__).parent / 'cli').iterdir()))"

The list has no templates or config_editor entry.

How do I run it in Docker Compose or Kubernetes?

docker compose --env-file prod.env up --build -d

docker build -t registry.example.com/my-agent:1.0 .
docker push registry.example.com/my-agent:1.0
# edit the image field in k8s.yaml, then:
kubectl apply -f k8s.yaml

Choose your deployment path

Before building, decide whether you need persistence, multiple instances, and public access. This flowchart guides the decision:

flowchart TD
    A[Do you need public or team access?] -->|No| B[Stay local with 10xgraph api/play]
    A -->|Yes| C[Do you need persistence?]
    C -->|No| D[Single-instance simple deployment]
    C -->|Yes| E[Shared durable checkpointer]
    E --> F[Do you need multiple replicas?]
    F -->|No| G[Single durable instance]
    F -->|Yes| H[Load balanced multi-instance deployment]

For local development, 10xgraph api and 10xgraph play are sufficient. For shared or production use:

• Persistence required: Set a durable checkpointer (for example PgCheckpointer), either in your graph code or with the checkpointer key in 10xgraph.json. In-memory checkpointing loses all threads on restart.
• Multiple instances: Use a shared durable checkpointer and a shared store (if using long-term memory). Each instance must access the same database backend.
• Rate limiting across instances: Use the redis rate-limit backend (the memory backend counts per process and is not shared).

Production environment settings

The generated files set MODE=production and IS_DEBUG=false. Add the following at runtime:

For durable persistence and distributed deployments, also configure:

• A PgCheckpointer or equivalent (never rely on in-memory checkpointing in production).
• A BaseStore subclass if you use long-term memory.
• An AuthorizationBackend to enforce thread ownership or role-based access control.

Full reference is in the configuration and environment pages.

Before release: verification checklist

Before deploying to production, run these checks to catch configuration issues early:

1. Health endpoint

   curl http://127.0.0.1:8000/ping

2. Graph schema

   curl http://127.0.0.1:8000/v1/graph

3. Auth is enforced (if enabled)

   • Without credentials: auth-protected routes return 401
   • With valid credentials: requests succeed

4. CORS is restricted

   • Requests from allowed origins succeed
   • Requests from disallowed origins are rejected

5. Documentation is hidden (if intentional)

   • In MODE=production the server turns /docs and /redocs off unless you set DOCS_PATH or REDOCS_PATH explicitly (they should return 404)
   • Check that neither variable is set in your deployment

6. Persistence survives restart

   • Invoke an agent and save the thread_id
   • Restart the server or container
   • Fetch the same thread: messages and state should be intact

7. Multiple instances sync (if deployed with replicas)

   • Invoke an agent on instance A, get a thread_id
   • Fetch that thread on instance B: state should be identical
   • This confirms the checkpointer and store backends are shared

Record the results before going live. If any check fails, fix the configuration and repeat.