Configuration
The default configuration is ~/.claude-gateway/config.json. Set GATEWAY_CONFIG to use a different file. The gateway loads ~/.claude-gateway/.env on startup; agent-specific environment files are configured through agents[].env.
Start from generated configuration
First boot creates a valid empty-agent configuration. Use the agent wizard to add required workspace and connection fields. The repository's config.template.json is a starting template; it includes migration metadata and placeholder credentials, so do not overwrite a working configuration with it blindly.
The following is a partial configuration. Merge the shown fields into the existing gateway object while retaining your agents and keys:
{
"gateway": {
"bind": "127.0.0.1",
"timezone": "UTC",
"headless": true,
"history": {
"retentionDays": 60,
"cleanupHour": 0,
"cleanupTimezone": "UTC"
}
}
}Website checks validate JSON syntax only; they do not compare fields or types against the repository template or config schema. The gateway loader performs runtime configuration validation when loading your configuration.
Settings by purpose
| Setting | Purpose |
|---|---|
gateway.bind / GATEWAY_BIND | Listening interface; environment override takes precedence |
PORT | Listening port, default 10850 |
gateway.publicUrl | Externally reachable origin for share links, image references, and /cli |
gateway.api.keys | API credentials and agent/write/admin scope |
gateway.models | Fallback model catalog |
agents[].workspace | Agent source workspace |
gateway.workers.environment / agents[].workers.environment | Explicit host worker environment; agent values override by key |
gateway.workers.containerEnvironment / agents[].workers.containerEnvironment | Separate app-worker environment; does not inherit host settings |
agents[].pstack | Sets the agent up for the pstack Claude Code plugin, with per-role model IDs; see pstack |
agents[].orchestration.tasks.projectRoot | Default worker project directory; preserves the Agent identity workspace |
agents[].session | Legacy idle timeout and concurrency |
gateway.history / agents[].history | Chat/media retention |
gateway.memory, gateway.knowledge, gateway.dreaming | Memory budget, indexing, consolidation |
gateway.sessionCompaction / agents[].sessionCompaction | Optional nightly native session compaction; see memory settings |
gateway.skillLearning | Automatic skill review and limits |
agents[].isolateMemory | Per-conversation USER.md/MEMORY.md for a host agent that serves many unrelated senders. An app agent gets it from its app.yaml instead; see memory settings |
Fresh configurations and the server fallback bind to 127.0.0.1. Migration preserves older externally reachable deployments by pinning 0.0.0.0 when needed; check your actual configuration after upgrading. A public URL does not itself configure a reverse proxy or make a loopback server reachable.
Credentials and scope
Environment placeholders use ${VARIABLE_NAME} syntax. Keep actual values in the appropriate environment file. Admin access requires admin: true; agents: "*" alone is not an admin grant. Use a scoped key for integrations and retain an admin key for gateway management.
Run claude-gateway doctor after changes, then verify the affected capability. Config migration adds new defaults and backs up the previous configuration; preserve those backups when upgrading. Some configuration changes hot-reload, while operations that replace installed code require a restart.
Continue with gateway settings, memory and knowledge settings, orchestration settings, voice configuration, or Jev evaluations.
Enable orchestration
gateway.orchestration is a single boolean, applying to every agent and channel. Per-agent orchestration holds tuning, not a second enable switch. Voice settings belong in agents[].voice. Enabling orchestration normalizes and persists gateway.headless: true. Its process supervisor supports Linux, macOS, and Windows.
{
"gateway": { "orchestration": true, "headless": true }
}For a new deployment, create the agent first using the wizard, then merge this block into the generated configuration. Use voice setup to configure speech separately. gateway.orchestration: false retains the legacy conversation path and hides orchestration-only commands.
Applying changes
Saving JSON, loading valid configuration, and applying it to a running component are separate operations. A saved value is not proof that an existing model process, channel connection, or scheduler has adopted it. See Applying configuration changes for the lifecycle, environment precedence, and verification steps.
- Live settings affect subsequent operations in the running gateway.
- Process settings take effect when the affected process is next created; they cannot change the environment or tool inventory of an existing CLI process.
- Connection and scheduling settings need the affected component to reconnect or reschedule.
- Startup settings and installed code require a gateway restart. Check active conversations and tasks first.
Voice settings changes apply to new voice connections and later replies; reconnect a live voice session to use the new settings consistently.
Do not copy an entire example over an existing config: this can discard agent entries, credentials, and unrelated settings. The API offers scoped updates to individual resources.
See worker command environment for startup-hook examples, native shell differences, reserved variables, and container behavior.
Computer Use via Jev
Without Jev, gateway.computerUse.enabled lets the agent's own model decide each step; see Computer Use without Jev.
gateway.jev.features.computerTasks.enabled controls Gateway-managed desktop execution (defaults to enabled when Jev is enabled). Agent Jev allowlists and connector enablement still apply. Set it to false to disable new desktop work; active runs check authorization before further actions. The shared gateway.jev.thinking provides text and independent goal verification. gateway.jev.features.computerSteps.enabled (default false) runs an explicit user step list on one desktop lease without a parent-agent turn between steps. See Step-by-step commands. gateway.jev.images.enabled (default false) lets Jev decide on screenshots: with gateway.computerUse.mode hybrid or vision, each desktop step is one Jev request on the window screenshot (pinned to gateway.jev.images.model, default jev-1.14.0), and Remote Browser decisions also carry the tab screenshot. See Image decisions on Jev.
Remote Browser direct commands via Jev
gateway.jev.features.browserTasks.enabled controls Gateway-managed Remote Browser tasks. While the user controls a browser task, each command runs as a direct command (fast paths for scroll, keys, back/forward, search and opening a site; otherwise one Jev decision). gateway.jev.features.browserSteps.enabled (default false, applied on live reload) runs an explicit user step list on one tab lease without a parent-agent turn between steps, with the same 12-step and 120-second limits as computerSteps. See Remote Browser direct commands. Pairing credentials belong in connector secrets, never in prompts or agent containers. See Computer Use connectors for discovery, scoped targets, local consent and restart behavior.