Skip to main content
Use Compose when the whole platform fits on one host and you do not need horizontal scaling or rolling updates. It is the fastest path to a running system and the one the repository exercises most. Use Kubernetes instead when you need more than one replica of anything, or when you want MCP server instances and agent sandboxes confined by a RuntimeClass — the Compose stack drives MCP containers through the host Docker socket, which offers no kernel isolation.
Compose is a single-tenant deployment. Every workspace’s agent code runs in one shared sandbox-executor container on the host kernel (SANDBOX_SHARED_EXECUTOR_ALLOW_WEAK_ISOLATION_FOR_DEVELOPMENT), and MCP containers share the host Docker daemon. Do not open sign-up to people you do not trust on a Compose install; run untrusted, multi-tenant workloads on Kubernetes with a gVisor RuntimeClass.
Two Compose files sit at the repository root: This guide covers docker-compose.yaml.

​
Prerequisites

  • Docker Engine 20.10 or later with Compose v2 (docker compose, not docker-compose)
  • A clone of the repository — the Compose file bind-mounts ./config/auth/kratos and ./agentarea-platform/temporal-config, so it does not run standalone
  • Ports 3000, 4433, 7999, 8000 free on the host, plus 5432, 6379, and 9000 if you publish them
  • See requirements for the full list

​
Steps

1

Create the environment file

.env.example leaves every signing key empty. gen-dev-secrets.sh writes a fresh value into .env for each key the Compose file requires with no default: the Kratos signing key, the Ory secrets, the sandbox and MCP gateway HMAC keys, and the OpenFGA preshared key. It keeps values you already set, except a sandbox or MCP gateway key that still holds a value an older .env.example shipped. Those values are public, and the services refuse to start on them.
2

Generate the secrets that must not stay at their defaults

AGENTAREA_SECRET_ENCRYPTION_KEY is the Fernet key that encrypts every stored credential — LLM provider keys, MCP server secrets — in the agentarea database. It must be a valid Fernet key, and it must not change after data exists, or the ciphertext already written becomes unreadable.
Set it in .env, together with real database and object-store credentials:
3

Start the stack

Or, equivalently, make up — which runs the same file in the foreground.Compose brings services up in dependency order:
  1. db becomes healthy (pg_isready), and rustfs becomes healthy.
  2. postgres_init creates the agentarea, temporal, and kratos databases. It is idempotent.
  3. app_migrations runs agentarea-api migrate with working directory /app/apps/api, and kratos-migrate runs the Kratos schema migration. bucket-init creates the two object-storage buckets and gives them the CORS allowlist browsers need for direct uploads (AGENTAREA_S3_CORS_ORIGINS, default http://localhost:3000).
  4. app, frontend, agentarea-worker, agentarea-events, agentarea-mcp-manager, sandbox-executor, temporal, and kratos start.
The one-shot containers (postgres_init, app_migrations, kratos-migrate, bucket-init) exit 0 and stay in Exited state. That is the expected result, not a failure.temporal has a 120-second start_period on its health check, and agentarea-worker waits for it. First start therefore takes a couple of minutes before tasks can run.
4

Reach the platform

Compose exposes Kratos directly and does not install a reverse proxy. Before exposing the host, place Kratos behind an operator-managed proxy and rate-limit /self-service/* by client IP.The Compose file publishes no ports for PostgreSQL, Valkey, RustFS, Temporal, or the event service. They are reachable only on the Compose networks.

​
Verify

Check that the long-running services are up and the one-shot jobs completed:
Every one-shot container should show Exited (0). Any other exit code means that step failed and the services depending on it did not start. Check the two HTTP health endpoints:
The API returns its status, service name, version, connection health, and a timestamp:
Confirm the migrations actually applied, rather than the stack merely being up:
Look for Migrations completed successfully. Stamped database to head revision is also a success — it means the schema already existed and Alembic recorded the current head without replaying migrations.

​
Troubleshooting

The Compose file uses ${VAR:?message} for the sandbox and MCP gateway secrets, so an empty value aborts the run rather than starting an unauthenticated sandbox path. Run ./scripts/gen-dev-secrets.sh to fill them.
A sandbox or MCP gateway key still holds a value an older .env.example or docker-compose.dev.yaml shipped. Anyone can sign tokens with it. Run ./scripts/gen-dev-secrets.sh, which replaces it, then restart the stack so every service picks up the new value.
The default secret backend is database , which requires a Fernet key. SecretManagerFactory validates this at construction time and raises, so the process exits at startup instead of failing later on the first secret read. Generate a key as in step 2.
Read docker compose -f docker-compose.yaml logs app_migrations . The migration command prints Migration failed: followed by the cause. A dirty database — one with tables from another product but no provider_specs table — makes Alembic apply migrations onto a schema it does not own. See [database and migrations](/self-host/database-and- migrations) .
postgres:18 stores data under /var/lib/postgresql/<version>/docker , so the Compose file mounts ./data/postgres at /var/lib/postgresql , not at the legacy /var/lib/postgresql/data . A data directory laid out for the old mount point will not start under this file.
agentarea-worker waits for temporal to pass its health check, which has a 120-second start period. Check docker compose -f docker- compose.yaml logs temporal and confirm the worker is running.
docker compose down -v removes volumes. The platform’s data lives in bind mounts under ./data/ (postgres, rustfs , valkey ), so down -v does not remove it — but rm -rf ./data does. See backup and recovery .

Requirements

Host, cluster, and dependency versions required to run AgentArea, per deployment target

Configuration

Every environment variable each AgentArea service reads, and the Helm value that sets it

Deploy on Kubernetes with Helm

Install the agentarea Helm chart, decide which bundled dependencies to keep

Choose a secrets backend

Configure where AgentArea stores workspace secrets

Troubleshoot a self-hosted deployment

Diagnose a deployment that will not start
Last modified on October 4, 2026