Docker

Quick Start

npx sim-setup

Open http://localhost:3000

The setup package creates ./sim with a generated .env and the production Compose file, then starts published container images. Pass --dir <path> to choose another directory.

Production Setup

1. Configure Environment

For a new installation, create the configuration below. If you already ran the quick start, edit its generated .env and retain the existing secret values; do not overwrite them with new keys.

cat > .env << EOF
BETTER_AUTH_SECRET=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
INTERNAL_API_SECRET=$(openssl rand -hex 32)
API_ENCRYPTION_KEY=$(openssl rand -hex 32)
CRON_SECRET=$(openssl rand -hex 32)

# Your public origin. BETTER_AUTH_URL is derived from this automatically.
NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com

# Database credentials. DATABASE_URL is composed from these by the compose file.
POSTGRES_USER=postgres
POSTGRES_PASSWORD=$(openssl rand -hex 24)
POSTGRES_DB=simstudio
EOF

The compose file refuses to start if BETTER_AUTH_SECRET, ENCRYPTION_KEY, or INTERNAL_API_SECRET is missing, rather than booting with empty values. CRON_SECRET is treated more gently: without it the cron service prints what to set and exits, leaving the rest of the stack running — so upgrading from a compose file that predates the scheduler still works.

Images track latest unless you pin them. For production, see Upgrades.

2. Start Services

docker compose -f docker-compose.prod.yml up -d

Six services start:

Confirm the five long-running services are up and that migrations has exited cleanly (it is a one-shot job with no healthcheck):

docker compose -f docker-compose.prod.yml ps

3. Put it behind TLS

Caddy is the least-effort option — it obtains and renews certificates automatically.

sim.yourdomain.com {
    request_body {
        max_size 250MB
    }

    handle /socket.io/* {
        reverse_proxy localhost:3002
    }

    reverse_proxy localhost:3000 {
        flush_interval -1
    }
}

Three things in that config are Sim-specific and easy to get wrong: /socket.io must reach the realtime service on 3002, flush_interval -1 stops Caddy buffering streamed agent output into one delayed block, and max_size has to clear the chat endpoint's 220 MB limit.

For nginx, Traefik, or a cloud load balancer — and for the GKE websocket timeout — see Networking.

Ollama

docker-compose.ollama.yml is a development stack, not a drop-in swap for docker-compose.prod.yml. It builds simstudio, realtime, and migrations from the source checkout instead of pulling published images, and it ships neither a redis service nor a cron service. Without an external Redis, pub/sub falls back to a process-local emitter and API-key login through the CLI pairing-code flow fails, since that approval store has no fallback; the idempotency store and execution progress markers do fall back to Postgres. And with no cron service, every background job is missing. For production with local models, keep docker-compose.prod.yml and point OLLAMA_URL at an Ollama instance, as under External Ollama below.

Always pass a server profile alongside setup. With --profile setup on its own no Ollama server starts and model-setup waits forever.

# With GPU
docker compose -f docker-compose.ollama.yml --profile gpu --profile setup up -d

# CPU only
docker compose -f docker-compose.ollama.yml --profile cpu --profile setup up -d

The setup profile pulls gemma3:4b as a starter model. Pull additional models — the service name differs by profile:

# GPU profile
docker compose -f docker-compose.ollama.yml exec ollama ollama pull llama3.2

# CPU profile
docker compose -f docker-compose.ollama.yml exec ollama-cpu ollama pull llama3.2

External Ollama

If Ollama runs on your host machine (not in Docker):

Set it in the .env next to your Compose file. A one-shot shell prefix satisfies the interpolation for that command only, so the next up -d silently reverts to the http://localhost:11434 default and the container points at itself:

# .env — macOS/Windows
OLLAMA_URL=http://host.docker.internal:11434

# Linux - use your host IP
# OLLAMA_URL=http://192.168.1.100:11434

docker compose -f docker-compose.prod.yml up -d

LM Studio

LM Studio exposes an OpenAI-compatible API. Start its local server, load a model, and enable Serve on Local Network so the Docker container can reach it. Enable API authentication, then set the endpoint and token in the .env file next to your Compose file:

# macOS/Windows
VLLM_BASE_URL=http://host.docker.internal:1234

# Linux - use your host IP instead
# VLLM_BASE_URL=http://192.168.1.100:1234

VLLM_API_KEY=your_lm_studio_api_token

Both the server root shown above and a URL ending in /v1 are accepted. After recreating the simstudio service, its models appear in the model picker with a vllm/ prefix; Sim removes that prefix before sending the model identifier to LM Studio.

# Pick the file that started your install.
COMPOSE_FILE=docker-compose.prod.yml
# COMPOSE_FILE=docker-compose.local.yml
# COMPOSE_FILE=docker-compose.ollama.yml
docker compose -f "$COMPOSE_FILE" up -d --force-recreate simstudio

The sim-setup CLI

npx sim-setup also manages an existing install created from the production or local-development Compose files. It does not detect or manage an Ollama-stack install. Run doctor, config, and the wizard from the directory holding your .env and Compose file; the lifecycle commands find a running stack wherever it was started. The table drops the npx prefix for brevity — keep it unless you installed the package globally.

--dir <path> is accepted by every command, not just the wizard. On a standalone install it also scopes the lifecycle commands to that directory's install, which is how you disambiguate when more than one exists.

Commands

# Did migrations succeed?
docker compose -f docker-compose.prod.yml logs migrations

# Is the scheduler firing?
docker compose -f docker-compose.prod.yml logs -f cron

# Upgrade: bump SIM_VERSION in .env when pinned, then
npx sim-setup update