environment.md

Environment variables

API endpoint and proxy routes

Variable	Effect
ANTHROPIC_BASE_URL	Override the Anthropic endpoint with an HTTP(S) URL
ANTHROPIC_INSECURE	OpenCode 1 TLS opt-out: 1 or true, effective only with ANTHROPIC_BASE_URL; avoid outside controlled diagnostics
ANTHROPIC_CUSTOM_HEADERS	Add proxy metadata on API-key routes; ignored for OAuth
ANTHROPIC_MODEL	Default proxy alias for any claude-* model
ANTHROPIC_DEFAULT_SONNET_MODEL	Alias for claude-sonnet-*
ANTHROPIC_DEFAULT_OPUS_MODEL	Alias for claude-opus-*
ANTHROPIC_DEFAULT_HAIKU_MODEL	Alias for claude-haiku-*
ANTHROPIC_DEFAULT_FABLE_MODEL	Alias for claude-fable-* and claude-mythos-*

Model aliases apply only to API-key/proxy routes; a family-specific alias takes precedence over ANTHROPIC_MODEL. OAuth requests retain their model identity and Claude Code headers.

ANTHROPIC_CUSTOM_HEADERS accepts a JSON object or comma/newline-separated name: value entries. Invalid or protected entries reject the entire configuration with a redacted warning. Authentication (Authorization, x-api-key), Anthropic protocol (anthropic-beta, anthropic-version), body-framing (such as Content-Length) and internal correlation headers (such as x-session-affinity) cannot be overridden.

Base URL paths are preserved: https://proxy.example/anthropic targets /anthropic/v1/messages; https://proxy.example/anthropic/v2 targets /anthropic/v2/messages. Version segments are not duplicated; unrelated paths ending in /messages are not rewritten. See transports.

Storage, custody and host paths

A legacy sidecar is an old migration-source file. The native files beside it store account definitions/settings (pool), per-account metadata (runtime) and setup/migration authority (journal); see the file map.

Variable	Effect
OPENCODE_ANTHROPIC_AUTH_FILE	OpenCode legacy sidecar path; its directory determines native pool/runtime/journal paths
PI_ANTHROPIC_AUTH_FILE	Pi legacy sidecar path; its directory determines Pi's native paths
OPENCODE_ANTHROPIC_AUTH_STATE_FILE	Legacy credential-state source for migration; also used by legacy Pi source resolution
OPENCODE_ANTHROPIC_AUTH_CLAUSTRUM_ENROLLMENT_FILE	OpenCode owner-only enrollment-token path; the companion state path is derived beside it
PI_ANTHROPIC_AUTH_CLAUSTRUM_ENROLLMENT_FILE	Pi enrollment-token path and derived companion state path
OPENCODE_ANTHROPIC_AUTH_CLAUSTRUM_CONNECTION_FILE	OpenCode Claustrum connection file
PI_ANTHROPIC_AUTH_CLAUSTRUM_CONNECTION_FILE	Pi Claustrum connection file
CLAUSTRUM_SUBC_CONNECTION	Shared fallback connection-file override
OPENCODE_ANTHROPIC_AUTH_ROUTING_STATE_FILE	OpenCode local routing destination when initializing/migrating
PI_ANTHROPIC_AUTH_ROUTING_STATE_FILE	Pi local routing destination when initializing/migrating
OPENCODE_CONFIG_DIR	OpenCode config directory override
OPENCODE_TUI_PREFERENCES_FILE	Full path override for the optional shared tui-preferences.jsonc
PI_CODING_AGENT_DIR, PI_AGENT_DIR	Pi extension default storage directory, in that precedence order
XDG_CONFIG_HOME	Base for the default OpenCode config directory
XDG_DATA_HOME	Base for OpenCode's data directory used to resolve OC1 auth.json during setup
XDG_STATE_HOME	Base for default enrollment files, cortexkit/anthropic-auth/<host>-enrollment.json; otherwise ~/.local/state

A completed import records its routing destination in the journal; serving uses that recorded path rather than retroactively relocating it when an override changes. See local storage. Pi SDK login-path resolution uses PI_CODING_AGENT_DIR (including home expansion), not the extension-only PI_AGENT_DIR fallback; the two are not interchangeable for host auth.

Host behavior and diagnostics

Variable	Effect
OPENCODE_ANTHROPIC_AUTH_FALLBACK_MODE	OpenCode 1: legacy skips Anthropic's server fallback and uses client safety recovery; default tries the server first, then client recovery
OPENCODE_ANTHROPIC_AUTH_CONTENT_FILTER_FALLBACK	OpenCode 2 wire policy: legacy disables its server-side fallback opt-in; it does not enable OC1's client recovery
OPENCODE_ANTHROPIC_AUTH_CACHEKEEP_REGISTRY_DIR	OpenCode 1 temporary CacheKeep session-lease directory
PI_ANTHROPIC_AUTH_CACHEKEEP_REGISTRY_DIR	Pi temporary CacheKeep session-lease directory
OPENCODE_ANTHROPIC_AUTH_QUOTA_FEED_DIR	OpenCode 1 quota-header-feed lease directory; publishing still requires quotaHeaderFeed.enabled
OPENCODE_ANTHROPIC_AUTH_RPC_DIR	OpenCode TUI menu bridge's port/token directory; default is per-project under OpenCode state
OPENCODE_ANTHROPIC_AUTH_PERF	1 enables structural request/relay/stream performance instrumentation

The sidebar guide, quota feed, safety fallback and dump guide explain scope and sensitive artifacts. The OpenCode TUI menu bridge accepts connections only from the local machine (127.0.0.1) and requires its bearer token.

CLI inputs

Variable	Effect
OPENCODE_ANTHROPIC_AUTH_API_BASE_URL	API fallback base URL for api add
OPENCODE_ANTHROPIC_AUTH_API_KEY	Secret API fallback key for api add
OPENCODE_ANTHROPIC_AUTH_API_AUTH_HEADER	authorization-bearer or x-api-key for api add
CLOUDFLARE_API_TOKEN	Token used to create/update the Cloudflare relay Worker with bunx @cortexkit/opencode-anthropic-auth relay setup; not stored as relay settings
CLOUDFLARE_ACCOUNT_ID	Cloudflare account ID for relay setup

Treat secret environment values as credentials; do not include them in logs or issue reports.

Implementation: proxy headers, model remapping, OpenCode endpoint handling, host setup paths, native setup paths, Pi paths, enrollment paths, OpenCode 2 wire policy, and CLI inputs.