Security & TLS

Nothing in the stack terminates TLS: the UI and the API serve plain HTTP. In production you put a reverse proxy in front of the stack to handle certificates, point the app at the HTTPS origins, and keep the plaintext ports off the network. This page covers that for Standalone and Distributed, plus where production secrets should live and how code evals are isolated. On Kubernetes, TLS sits on the Gateway API route or Ingress that exposes the Helm chart: see Install for production.

Terminate TLS with a reverse proxy

Run Caddy, nginx, or Traefik on the host in front of the stack. Caddy is the shortest path because it issues and renews Let’s Encrypt certificates on its own.

# Caddyfile
app.example.com     { reverse_proxy 127.0.0.1:3000 }   # UI
api.example.com     { reverse_proxy 127.0.0.1:8000 }   # API
files.example.com   { reverse_proxy 127.0.0.1:9005 }   # object storage
traces.example.com  { reverse_proxy 127.0.0.1:4318 }   # trace collector (OTLP/HTTP)
gateway.example.com { reverse_proxy 127.0.0.1:8090 }   # LLM gateway

sudo cp Caddyfile /etc/caddy/Caddyfile
sudo systemctl reload caddy

VITE_HOST_API=https://api.example.com
BASE_URL=https://api.example.com
FRONTEND_URL=https://app.example.com
APP_URL=https://app.example.com
MINIO_URL=https://files.example.com
FI_COLLECTOR_PUBLIC_URL=https://traces.example.com

docker compose up -d
curl -sI https://app.example.com | head -1     # expect HTTP/2 200

docker compose --env-file deploy/.env.production \
  -f docker-compose.distributed.yml -f deploy/docker-compose.production.yml \
  up -d --no-build --wait --wait-timeout 1200

Keep secrets out of .env

These files hold the production secrets in plain text:

Provider keys you add (OPENAI_API_KEY and the like) and MAILGUN_API_KEY sit in the same file. ./bin/install creates .env readable only by your user; keep it that way.

For anything past a single trial host, keep the source of truth in a dedicated manager instead of a file on disk:

• AWS Secrets Manager
• HashiCorp Vault
• GCP Secret Manager

Replace the published defaults first: the Checklist lists them and what breaks when one changes later. Then inject the values at deploy time. Compose gives a variable exported in your shell precedence over .env when it fills the compose files’ ${VAR} references. deploy/setup.sh is the exception: it clears exported secrets before Compose reads deploy/.env.production, so with the overlay, write the values into that file. Whichever way you inject them, PG_PASSWORD, INTEGRATION_ENCRYPTION_KEY and CH_PASSWORD must keep the values the data was created with.

Isolate the code executor

Custom code evals run code your users write. How it is isolated depends on the setup:

• Standalone: Python evals run inside the app container as an unprivileged user, with an empty environment, resource limits and a private temporary directory. That user cannot read the app’s data or mounted secrets. On Docker hosts with Linux 6.7 or later and Landlock, evals may connect only to TCP ports 80 and 443 (CODE_EXECUTOR_EGRESS_PORTS); on older kernels they can reach the Temporal dev server, Postgres and ClickHouse over the Docker network. This suits installs where everyone who can write a code eval is trusted with the data. Otherwise set COMPOSE_PROFILES=sandbox in .env and run ./bin/install again: every run then gets its own nsjail jail with a read-only view of the filesystem. The sandbox profile needs privileged containers, and JavaScript evals run only with it.
• Distributed: code evals always run in the nsjail code-executor, which needs privileged: true. It listens on 127.0.0.1:8060 only and runs any code it is sent, without authentication: never publish that port. CODE_EXECUTOR_LOCAL_FALLBACK=true runs code evals inside the worker, next to the platform’s secrets, when code-executor cannot be reached; use it only on a platform that cannot run code-executor and where everyone who can write a code eval is trusted.
• Helm: the sandbox is off by default (codeExecutor.enabled), and custom code evals are refused until you turn it on on nodes that allow privileged pods. With networkPolicy.enabled, the chart blocks the sandbox from every private, link-local and metadata address.

nsjail still allows network access, in both the sandbox profile and Distributed. On any install that holds sensitive data, keep code-eval authorship to people you trust with the databases.

Private provider URLs

AGENTCC_ALLOW_PRIVATE_PROVIDER_URLS (default false) lets the providers an organization adds use base URLs on private networks, such as a local Ollama or vLLM server. With it on, anyone who can add a provider can point the gateway and the API at any address on those networks, the databases included. Leave it off unless everyone who can add a provider is trusted. Loopback, link-local and cloud metadata addresses stay refused either way. Setup and examples are in Private and local provider URLs.

Dive deeper