Configuration¶
Everything is configured with environment variables. Four are required; the rest have safe defaults.
MULTICA_TOKEN=...
AI_BASE_URL=...
AI_API_KEY=...
AI_MODEL=...
How values are resolved¶
The AI_* variables are a friendly layer over the native variables the agent
CLIs already understand. Native variables win when both are set, so existing
deployments can move over one value at a time.
| Public | Native equivalent | Notes |
|---|---|---|
AI_BASE_URL |
ANTHROPIC_BASE_URL |
Required |
AI_API_KEY |
ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY |
Required |
AI_MODEL |
ANTHROPIC_MODEL |
Recommended |
AI_MODEL_LARGE |
ANTHROPIC_DEFAULT_OPUS_MODEL |
Optional tier |
AI_MODEL_MEDIUM |
ANTHROPIC_DEFAULT_SONNET_MODEL |
Optional tier |
AI_MODEL_SMALL |
ANTHROPIC_DEFAULT_HAIKU_MODEL |
Optional tier |
AI_SUBAGENT_MODEL |
CLAUDE_CODE_SUBAGENT_MODEL |
Optional |
Conflicting values are not silently merged: the container logs a warning and uses the native variable.
Credential style¶
Anthropic's API expects an x-api-key header. Routers usually expect
Authorization: Bearer. The entrypoint picks based on what you set:
| You set | Header used |
|---|---|
ANTHROPIC_AUTH_TOKEN |
Bearer |
ANTHROPIC_API_KEY |
x-api-key |
AI_API_KEY + https://api.anthropic.com |
x-api-key |
AI_API_KEY + any other URL |
Bearer |
If a router only accepts one style, set the native variable explicitly. The
startup banner prints auth=bearer or auth=api-key — never the key.
Multica¶
| Variable | Required | Default | Meaning |
|---|---|---|---|
MULTICA_TOKEN |
yes | — | Personal access token |
MULTICA_SERVER_URL |
no | Multica Cloud | Self-hosted server URL |
MULTICA_WORKSPACE |
no | — | CLI default workspace |
MULTICA_DAEMON_WORKSPACE_ALLOWLIST |
no | all reachable | Comma-separated workspace ids/slugs the daemon may register in |
MULTICA_DAEMON_ID |
no | container hostname | Stable runtime identity |
MULTICA_AGENT_RUNTIME_NAME |
no | Multica Runtime |
Name shown in the dashboard |
MULTICA_DAEMON_MAX_CONCURRENT_TASKS |
no | daemon default | Parallel tasks per runtime |
MULTICA_WORKSPACES_ROOT |
no | /workspaces |
Where task directories and sessions live |
Set MULTICA_DAEMON_ID¶
If unset, the container hostname is used, and every restart creates a new runtime. Agents bound to the old runtime id do not automatically follow the new one. Always set a stable id:
MULTICA_DAEMON_ID=multica-php
One id per role. Never run two containers with the same id: they will compete for the same tasks.
Workspace scope¶
MULTICA_WORKSPACE only sets the CLI default. The daemon may register in every
workspace the token can reach. If the token belongs to several workspaces, scope
it explicitly:
MULTICA_DAEMON_WORKSPACE_ALLOWLIST=acme,acme-sandbox
AI router¶
| Variable | Default | Meaning |
|---|---|---|
AI_PROTOCOL |
auto |
auto / openai / anthropic |
AI_PROVIDER_ID |
multica |
OpenCode provider id; models appear as <id>/<model> |
AI_MODELS_PROBE |
1 |
Set 0 to skip the /v1/models probe |
AI_MODELS_URL |
<origin>/v1/models |
Override the probe URL |
Protocol detection¶
OpenCode talks to your endpoint through one of two adapters:
openai—@ai-sdk/openai-compatible, base URL<origin>/v1anthropic—@ai-sdk/anthropic, base URL as given
With AI_PROTOCOL=auto (the default), the entrypoint requests
<origin>/v1/models with your key. If it gets a model list, it uses openai;
otherwise it falls back to anthropic. The exception is api.anthropic.com:
its /v1/models answers, but its wire protocol is not OpenAI-compatible, so auto
always selects anthropic there. The probe is retried three times with a
10-second timeout.
Set AI_PROTOCOL when detection is wrong, and AI_MODELS_PROBE=0 on a network
where the probe cannot reach the router.
Model tiers¶
Claude Code asks for four model slots by name. On a router, the upstream ids
(claude-sonnet-4-5, …) may not exist. Anything you do not pin is therefore
derived from AI_MODEL — always valid, but it spends the main model on every
slot.
For better cost/latency, pin the tiers:
AI_MODEL=general
AI_MODEL_LARGE=reasoning
AI_MODEL_MEDIUM=general
AI_MODEL_SMALL=fast
AI_SUBAGENT_MODEL=fast
The entrypoint warns at startup if a pinned model is not in the router's catalogue.
Claude Code¶
| Variable | Default | Meaning |
|---|---|---|
CLAUDE_CONFIG_DIR |
/workspaces/.claude |
Transcripts and config |
MULTICA_CLAUDE_MODEL |
— | Passed through to the daemon |
MULTICA_CLAUDE_ARGS |
— | Extra CLI arguments |
DISABLE_AUTOUPDATER=1 and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 are set
by default: the CLI version is whatever the image pins. An in-place auto-update
would silently change behaviour under you.
OpenCode¶
| Variable | Default | Meaning |
|---|---|---|
XDG_DATA_HOME |
/workspaces/.opencode/data |
Session data |
OPENCODE_CONFIG |
$XDG_CONFIG_HOME/opencode/opencode.json |
Config path |
MULTICA_OPENCODE_MODEL |
AI_MODEL |
Main model |
MULTICA_OPENCODE_SUBAGENT_MODEL |
AI_SUBAGENT_MODEL |
Subagent model |
The entrypoint writes the config at container start because OpenCode does not read
ANTHROPIC_BASE_URL. The file contains your API key and is created with mode
0600.
Codex CLI¶
| Variable | Default | Meaning |
|---|---|---|
CODEX_HOME |
/workspaces/.codex |
Session data and config |
CODEX_BASE_URL |
<router origin>/v1 |
Responses endpoint override |
CODEX_API_KEY |
AI_API_KEY |
Credential override |
CODEX_MODEL |
AI_MODEL |
Model override |
MULTICA_CODEX_MODEL |
— | Passed through to the daemon |
MULTICA_CODEX_ARGS |
— | Extra CLI arguments |
The entrypoint writes $CODEX_HOME/config.toml at container start to configure
a custom provider pointed at the router's Responses endpoint (/v1/responses).
check_for_update_on_startup = false is set to keep image-pinned versions.
Git hosting (optional)¶
| Variable | Meaning |
|---|---|
GH_TOKEN |
GitHub token for gh and HTTPS git |
GITHUB_TOKEN |
Fallback for GH_TOKEN |
GIT_AUTHOR_NAME |
Commit identity (default Multica Agent) |
GIT_AUTHOR_EMAIL |
Commit email (default agent@multica.invalid) |
With a token, gh auth setup-git is run so git push over HTTPS works without a
credential prompt.
The identity is written to the global Git config at start; Multica copies it into
every task checkout. Without one, commits fail with Author identity unknown
(see Troubleshooting).
PHP image¶
| Variable | Default | Meaning |
|---|---|---|
MULTICA_START_DATABASES |
1 |
Start embedded MariaDB/PostgreSQL/Redis |
MULTICA_DB_ROOT |
/tmp/multica-db |
Ephemeral data directory |
MULTICA_DB_NAME |
DB_DATABASE or laravel |
Database created at boot |
MULTICA_DB_USER |
DB_USERNAME or laravel |
Database user |
MULTICA_DB_PASSWORD |
DB_PASSWORD or secret |
Database password |
MULTICA_MYSQL_PORT |
3306 |
MariaDB port |
MULTICA_POSTGRES_PORT |
5432 |
PostgreSQL port |
MULTICA_REDIS_PORT |
6379 |
Redis port |
The entrypoint deliberately does not export DB_* variables, so it cannot
override your application's .env. Point the app at 127.0.0.1 yourself.
Data lives under /tmp and is recreated on every container start. That is
intentional: a runtime is disposable, a database inside it is not a source of
truth.
Design image¶
| Variable | Default | Meaning |
|---|---|---|
PENPOT_URL |
https://design.penpot.app |
Penpot instance |
PENPOT_MCP_SERVER_PORT |
4401 |
MCP HTTP port |
PENPOT_MCP_WEBSOCKET_PORT |
4402 |
Plugin WebSocket port |
PENPOT_MCP_PLUGIN_PORT |
4400 |
Plugin server port |
PENPOT_MCP_SERVER_HOST |
127.0.0.1 |
MCP bind address |
PENPOT_MCP_PLUGIN_SERVER_HOST |
127.0.0.1 |
Plugin bind address |
PENPOT_BROWSER_PROFILE |
/workspaces/.penpot-browser |
Persistent Chromium profile |
MULTICA_PENPOT_MCP |
1 |
Register the MCP server with both CLIs |
PENPOT_DISPLAY |
:99 |
Xvfb display |
PENPOT_SCREEN |
1440x1024x24 |
Xvfb screen |
Penpot credentials are not read by the entrypoint. The agent logs in through the real browser UI, and the session cookie stays in the persistent profile.
Autoscaler¶
See Autoscaling for the full list. The two variables that matter most:
AUTOSCALER_PLATFORM=ecs # or swarm
AUTOSCALER_RUNTIMES=[{"daemon_id":"multica-php","service":"multica-php"}]
Diagnostics¶
| Variable | Meaning |
|---|---|
MULTICA_DRY_RUN |
Resolve config, print the banner, exit without logging in |
AI_MODELS_PROBE |
Set 0 to skip the router probe |
Dry run is useful in CI and when debugging a bad key without hammering Multica:
docker compose run --rm -e MULTICA_DRY_RUN=1 runtime
Full template¶
The annotated template lives at
.env.example.