Configuration

Most of Control Tower is configured in the browser. Command-line flags and environment variables exist for operators.

#Command-line flags

controltower [options]            (docker: pass the same options after the image name)

  --config, -c <file>   load a config.yaml at startup
  --model, -m <p/model> serve one model with credentials from the environment
  --policy <file>       apply a policy YAML (zones and gates) at startup
  --port, -p <n>        listen port (default 4000)
  --host <addr>         listen address (default 0.0.0.0)
  --detailed_debug      verbose logs (also --debug)
  --copy-to-postgres <url>  copy this install's SQLite data into an empty Postgres database, then exit
                        (with no URL: uses CT_DATABASE_URL)
  --support-bundle [file]  write a report for whoever helps you — version, settings by name,
                        database, health, error counts; no keys, prompts or names — then exit
  --version, -v         print the version
  --help, -h            this list

controltower --config config.yaml --port 4000                 # from source: pnpm start --config config.yaml
docker run -p 4000:4000 -e OPENAI_API_KEY ghcr.io/joshmaster2165/controltower --model openai/gpt-4.1-mini   # agents ask for openai/gpt-4.1-mini

--num_workers is accepted and ignored: Control Tower is one process; to scale, run several instances on a shared Postgres and Redis.

#Admin key

Set CT_ADMIN_KEY — or general_settings.master_key in a config file — and it becomes:

1. the admin API bearer: Authorization: Bearer <admin key> works on every /admin/api/* route and on the /key/* and /model/* management routes;
2. an all-access key for model and tool calls (it appears on the map as master-key once used);
3. the console password for the user admin (change the name with UI_USERNAME, or the password alone with UI_PASSWORD). On a fresh install this account is created for you, so the first-run screen is skipped — useful for platform deploys and CI.

Rotating the variable rotates all three at the next start; when the console password changes with it, sessions signed in with the old one end. Use a long random value (sk-$(openssl rand -hex 32)); the server warns about short ones.

#First-run setup

Until an admin exists, the server prints a setup code in its startup log, and an Open link that carries it (http://localhost:4000/?setup=K7QM-4XTP-9HRD). The setup page asks for the code and the link fills it in. Without the right code, setup is refused (403 setup_code), so someone who reaches a new install before you can't claim it. With Docker, docker logs <container> shows it.

• The code is derived from the master key, so every instance sharing a database prints the same one. CT_SETUP_TOKEN sets it yourself, for scripts that call POST /admin/api/setup (it is still printed in the log).
• Setup attempts are limited to 10 a minute per address (429 rate_limited).
• Only one setup can succeed. Afterwards POST /admin/api/setup answers 409 already_setup, and the page is a sign-in.
• With CT_ADMIN_KEY set, a fresh install gets its admin sign-in from the key and has no setup page (above).

#Console sign-in and sessions

• Sign-in attempts are limited to CT_LOGIN_RPM a minute per email (default 10), and twice that per address. Over it, 429 rate_limited with retry-after. With Redis, the count is shared across instances.
• Sessions end after CT_SESSION_TTL_MS (7 days), or sooner after CT_SESSION_IDLE_MS without use (12 hours). The database keeps only a hash of each session cookie.
• Cookies are HttpOnly, SameSite=Lax, and Secure when the console is reached over HTTPS: CT_PUBLIC_URL starts with https://, or the request came in over HTTPS (directly, or through a proxy that sets X-Forwarded-Proto).
• Security headers: the console, the admin API and the gateway send X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: same-origin, and Strict-Transport-Security over HTTPS. Console pages add a Content Security Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self' ws: wss:; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'. Responses relayed from HTTP APIs (/http/…) keep their own headers.
• Live updates: the console's WebSocket (/admin/ws) refuses a browser from another origin (close code 4403). Behind a proxy that rewrites Host, set CT_PUBLIC_URL or pass X-Forwarded-Host.
• Errors: an unexpected server error answers 500 internal_error with the request id; the details are in the server's log, not the response.

#Environment variables

Provider keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, AWS_ACCESS_KEY_ID…) are read only by --config, --model and Import config; providers added in the console store their own credentials.

Variables other gateways use that don't apply here are reported at startup rather than silently ignored — for example DATABASE_URL (Control Tower uses SQLite in CT_DATA_DIR, or Postgres from CT_DATABASE_URL) and STORE_MODEL_IN_DB (models added in the console are always stored).