Configuration reference

How configuration is loaded#

The backend reads the environment at startup and validates the combination before it opens its port: if something is inconsistent, the process exits with an error that names the variable. The runtime reads its variables when it uses them. The frontend reads nothing at runtime: its values are fixed at build time.

• Booleans: true, false, 1, 0 and the other values accepted by strconv.ParseBool. An invalid value aborts startup.
• Integers and durations: a missing, non-numeric or non-positive value is replaced by the default. Durations use Go syntax (30s, 5m, 1h).
• USD amounts: 0 is valid and turns the corresponding cap off; a negative or non-numeric value keeps the default. The exception is BUDGET_USD, which needs a value above zero.
• Lists: comma-separated values; spaces are ignored.

Server and database#

Authentication, CORS and proxy#

With AUTH_ENABLED=false the backend runs in demo mode: one fixed organization and no sign-in. With AUTH_ENABLED=true it enables accounts, JWT, RBAC and per-organization isolation, and the org_id comes from the token.

With authentication on, startup fails if JWT_SECRET is shorter than 32 bytes, if DATABASE_URL is missing or if ALLOWED_ORIGINS contains *.

Budget, cost and execution limits#

These variables control spending and orchestrator concurrency. Context windows and quality checks have more internal settings with sensible defaults; this table covers the ones worth knowing.

Rewards and coins#

The coin system rewards completed work. REWARDS_RULES takes a JSON object that is applied on top of the default rules, so you only include the fields you want to change.

If the JSON has an invalid value, the backend logs it and uses the full default rules: it never applies a half-changed economy.

{
  "enabled": true,
  "base": { "S": 5, "M": 10, "L": 20, "XL": 40 },
  "default_complexity": "M",
  "first_try_bonus_pct": 50,
  "rework_pct": 50,
  "project_base": 20,
  "project_per_task": 2,
  "project_max": 100,
  "min_project_tasks": 2
}

Runtime: model providers and keys#

The runtime supports five providers: deepseek, anthropic, openai, kimi and custom (an OpenAI-compatible endpoint such as vLLM or Ollama). A provider counts as configured when its key (and, for custom, its base URL) is in the environment. With no provider configured, or with SIMULATION=true, the runtime uses the simulated engine: scripted answers, no keys and no cost.

On a transient error (timeout, rate limit, 5xx) it retries on the same provider and then moves to the next allowed one. ALLOWED_PROVIDERS is the operator ceiling: no data reaches an excluded provider, not even as a fallback. Each organization can narrow it further in its settings, never widen it, and can store its own provider key, which wins over the environment's.

Connections, sandbox, storage and push#

Without CONNECTIONS_KEK no live credential can be stored: the vault fails closed and only simulated connections work. The KEK is base64 of 32 random bytes; keep it apart from the database, because without it the encrypted secrets cannot be recovered.

The code sandbox is optional and needs the sandbox-runner service, which is given access to the Docker socket. Read the security model page first.

openssl rand -base64 32

Rate limits#

Rate limits are built into the backend and have no tuning variables: for example, 10 sign-in attempts per 15 minutes and 120 commands per minute. The authentication limits are stored in Redis when REDIS_URL is set, and in process memory otherwise.

What you do configure is TRUSTED_PROXIES. Only the X-Forwarded-For header from those proxies is used to identify the client. Behind Caddy, list the proxy network: without it, every client shares the proxy's IP and the same counter.

Frontend: build arguments#

The frontend is compiled with standalone output. NEXT_PUBLIC_* variables are baked in at build time as Dockerfile arguments (ARG); changing them means rebuilding the image.

Leaving them empty gives the recommended single-domain behavior: the API at the relative path /api/v1 and a WebSocket URL derived from window.location.

docker build \
  --build-arg NEXT_PUBLIC_API_URL=https://app.example.com/api/v1 \
  --build-arg NEXT_PUBLIC_WS_URL=wss://app.example.com/ws \
  -t aiworkforce-frontend ./frontend

Email verification and trial accounts#

Two optional sign-in features, both requiring AUTH_ENABLED=true. Email verification needs a working SMTP server: with EMAIL_VERIFICATION=true and no valid SMTP the backend refuses to start, so a half-configured server cannot lock anyone out.

Trial accounts let people use the app without signing up; each one gets its own organization and stops working on its own.