server.md

title	Server and Runtime Configuration
description	Listener, remote access, admission keys, timeouts, storage, sidecars, shadow calls, and startup behavior.

Server settings control how the local proxy listens, protects remote traffic, manages resources, and runs helper features around provider requests.

Server fields

Field	Type	Default	Meaning
port	number	10100	Proxy listen port.
hostname?	string	"127.0.0.1"	Bind address. Non-loopback binds require CODEXCOMMANDER_API_AUTH_TOKEN.
proxy?	string	—	Outbound HTTP(S) proxy URL or ${ENV_VAR}. Applied to HTTP_PROXY / HTTPS_PROXY only when those variables are unset; loopback remains in NO_PROXY.
stallTimeoutSec?	number	300	Seconds without upstream data before response.incomplete. Minimum 1.
connectTimeoutMs?	number	200000	DNS/TCP/TLS/final-header deadline; native forward Responses and compaction share it across initial send and account recovery. It ends before body generation.
shutdownTimeoutMs?	number	5000	Graceful drain deadline before active turns are aborted.
websockets?	boolean	false	Advertise supports_websockets for the Responses WebSocket path. False keeps HTTP/SSE.
corsAllowOrigins?	string[]	[]	Additional exact origins allowed by CORS. Loopback origins are always allowed. Authority-based browser extension origins such as chrome-extension://<extension-id> are supported; * is not a wildcard. Firefox and Safari regenerate the extension UUID (per install / per browser launch), so update the entry when the origin changes.
apiKeys?	CodexCommanderApiKey[]	[]	Generated ccx_data_… credentials accepted by data-plane auth on non-loopback binds. Dashboard-managed; these keys never authenticate /api/*.
storageCleanupPolicy?	StorageCleanupPolicy	disabled	Opt-in archived-session cleanup policy. Never enabled implicitly.
appOwnedMemoryBudgetMb?	number	256	Cap in MiB for evictable app-owned logs, caches, blobs, and continuation payloads. Range 64–4096; not an RSS cap.
codexAutoStart?	boolean	true	Let the Codex shim run ccx ensure before launching Codex. False makes ensure a no-op.
codexShimAutoRestore?	boolean	true	Restore an installed shim after a completed external Codex update replaces it. Environment opt-out: CODEXCOMMANDER_CODEX_SHIM_AUTO_RESTORE=0.
shadowCallIntercept?	{ enabled?: boolean; model?: string; sourceModels?: string[] }	off	Redirect recognized Codex helper/shadow calls to a chosen model at low effort. The default source prefix is gpt-5.6-luna; sourceModels is an explicit current custom-source override.
webSearchSidecar?	CodexCommanderWebSearchSidecarConfig	on when usable	Web-search sidecar options.
visionSidecar?	CodexCommanderVisionSidecarConfig	on when usable	Image-description sidecar options.
images?	CodexCommanderImagesConfig	automatic OpenAI selection	Standalone Images relay options for Codex image_gen.

Request recovery and cancellation

The shared upstream transport sends once by default. Connection resets and generic server errors are returned to the client instead of automatically repeating potentially processed inference. Native forward Responses and compaction permit at most one additional send for an existing allowlisted account rejection, such as a quota rejection when account fallback is allowed. Both sends share connectTimeoutMs; selecting a second account does not restart the deadline. Exact account selectors remain exact.

Cancelling a passthrough response immediately signals upstream cancellation and releases its reader. The proxy no longer waits up to 15 seconds for additional usage data. Completion evidence already received is retained; otherwise usage can remain partial or unknown. The provider controls when remote generation actually stops after receiving cancellation.

Explicit combo fallback, API-key retryOn429, and adapters with their own recovery policies are separate. Native clients can also retry errors themselves. These safeguards reduce proxy-generated work; they do not establish subscription-credit parity with native Codex.

Remote access

The default 127.0.0.1 bind is loopback-only. A non-loopback address such as 0.0.0.0 requires token authentication on both /api/* and the data plane. Export the token before starting:

export CODEXCOMMANDER_API_AUTH_TOKEN="your-secret-token"
ccx start

The proxy refuses a remote bind without this variable. For a background service, export it before ccx service install so launchd, systemd, or Task Scheduler receives it. Clients should send:

x-codexcommander-api-key: your-secret-token

Endpoint	Authorization: Bearer	x-codexcommander-api-key	x-api-key
/v1/responses	not accepted	required	not accepted
/v1/chat/completions	not accepted	required	not accepted
/v1/messages	accepted	accepted	accepted
/v1/models	accepted	accepted	accepted

Responses and Chat Completions reserve Authorization for possible Codex Direct passthrough, so only the dedicated admission header is accepted there. Dashboard-generated apiKeys may replace the environment token after startup; candidates are compared in constant time.

:::caution[LAN exposure] A 0.0.0.0 bind exposes the proxy and configured provider access to the LAN. Use it only on trusted networks with a strong token. :::

SSH port forwarding

Remote use does not require a remote bind. Keep loopback and forward it:

ssh -L 20100:localhost:10100 you@remote

Any local port works. Requests whose Host resolves to localhost, 127.0.0.1, or ::1 remain loopback regardless of port, so http://localhost:20100/v1 works. Set that base URL in the client; ccx writes only the default local 127.0.0.1 address into managed client config.

Provider OAuth callbacks listen on a fixed remote port. Log in on the remote machine or forward that port too:

ssh -L 20100:localhost:10100 -L 1455:localhost:1455 you@remote

:::caution[Forwarded loopback is unauthenticated] Plain ssh -L listens on your local loopback and is safe for the default unauthenticated bind. Do not use ssh -g -L, broad container publishing, or forwarding modes that expose the client side on 0.0.0.0. Bind explicitly with ssh -L 127.0.0.1:20100:localhost:10100 when unsure. :::

Storage cleanup

storageCleanupPolicy is disabled by default. When enabled, it runs on startup, daily, weekly, or manual after archived bytes exceed trigger.archivedBytesOver. It selects oldest archives toward either target.reduceToBytes or target.removeOldestPercent. mode defaults to quarantine; use permanent only as an explicit destructive choice. The policy persists lastRun and nextRun. Configure it on the Storage page or with GET/PUT /api/storage/cleanup-policy; trigger a manual run with POST /api/storage/cleanup-policy/run.

Claude Code (claudeCode)

These settings govern /v1/messages, the ccx claude launcher, and the Claude dashboard page.

Key	Type	Default	Description
claudeCode.bodyStallSec?	number	90	Native-passthrough body inactivity budget in seconds while a read is pending, not total duration. Minimum 1; exactly 0 disables.
claudeCode.bodyMaxBytes?	number	67108864	Cumulative native-passthrough body cap for streamed and buffered responses. Exactly 0 disables.
claudeCode.authMode?	"proxy" | "subscription"	auto	How launch handles ANTHROPIC_AUTH_TOKEN. Auto detects auth each launch; an explicit value is never overridden.
claudeCode.subagentEffort?	"low" | "medium" | "high" | "xhigh" | "max"	inherit	Effort written to generated ~/.claude/agents/ccx-*.md; separate from Codex guidance and proxy caps. Restart through ccx claude to regenerate.

Auto auth selects subscription when stored Claude auth is found, proxy when none is found, and subscription with a warning when detection is inconclusive. See Claude Code auth mode.

Shadow calls

Codex uses small helper models for tasks such as titles and commit messages. Enable shadowCallIntercept to redirect recognized source-model prefixes to another configured model. The replacement runs at low effort. Set sourceModels only as an explicit current custom-source override. Only recognized maintenance request kinds in x-codex-turn-metadata are eligible; normal turns and requests with missing, malformed, or unrecognized metadata are never intercepted.

{
  "shadowCallIntercept": {
    "enabled": true,
    "model": "gpt-5.5",
    "sourceModels": ["gpt-5.6-luna"]
  }
}

Sidecars

images (CodexCommanderImagesConfig)

Field	Type	Default	Meaning
provider?	string	automatic OpenAI selection	Explicit custom API-key openai-responses provider for the standalone Images relay.
timeoutMs?	number	300000	Whole-request timeout for one standalone Images request.

The /v1/images/generations and /v1/images/edits relay serves Codex built-in image generation. See Codex Integration for routing and provider-selection behavior.

webSearchSidecar (CodexCommanderWebSearchSidecarConfig)

Field	Type	Default	Meaning
enabled?	boolean	on when usable	Master switch.
backend?	"openai" | "anthropic"	auto	Explicit wins; otherwise usable stored Anthropic OAuth selects anthropic, then openai.
model?	string	backend-dependent	gpt-5.6-luna for OpenAI or claude-sonnet-5 for Anthropic.
reasoning?	string	low	Sidecar effort. minimal is rejected with web search.
maxSearchesPerTurn?	number	3	Real searches allowed per main-model turn.
routedModelStallTimeoutMs?	number	200000	Config-file-only routed-model raw-body inactivity deadline. Integer 1–2147483647; every non-empty chunk resets it.
timeoutMs?	number	60000	Deadline for one hosted search.
xSearch?	boolean	true	Adds the xAI x_search tool for Grok 4.7 turns on the xAI provider. false turns it off. See X search for Grok 4.7.

The OpenAI backend requires a ChatGPT login and enabled ChatGPT forward provider. Claude-inbound routed replays inject main ChatGPT auth into the internal request. The Anthropic backend uses the active stored credential from an enabled Anthropic OAuth provider. An explicitly selected Anthropic backend with no usable account fails closed instead of falling back. The Anthropic executor uses its native web_search_20250305 tool.

Four clocks govern search: base stallTimeoutSec, connectTimeoutMs, routed-model inactivity, and hosted-search timeout. The effective bridge watchdog is the maximum plus 30 seconds. Routed stall is an inactivity guard, not a total generation deadline.

visionSidecar (CodexCommanderVisionSidecarConfig)

Field	Type	Default	Meaning
enabled?	boolean	on when usable	Master image-description switch.
backend?	"openai" | "anthropic"	auto	Same explicit-first, Anthropic-credential-aware selection as web search.
model?	string	backend-dependent	gpt-5.6-luna for OpenAI or claude-sonnet-5 for Anthropic.
maxDescriptionsPerTurn?	number	8	New description cache misses admitted per main turn. 0 disables calls; invalid values use default.
timeoutMs?	number	45000	Sidecar fetch timeout.

Vision activates only for images sent to a model in its provider's noVisionModels. OpenAI has the same login/forward requirements as search; explicitly selected Anthropic fails closed without a usable credential. Successful data: descriptions use a bounded cache keyed by backend, model, detail, image bytes, and normalized message context. Hits and same-turn duplicates do not consume the limit. Remote https: images and failed or empty descriptions are not cached.

Anthropic OAuth sidecars reuse CodexCommander's existing Claude Code OAuth fingerprint. Soak-test the intended account and workload.