config.json

config.json is the relay's own configuration file: its port, who may reach it, the access token, the timers that decide when a turn counts as stuck, and the optional tunnels and preview lane. oar setup creates it. You edit it by hand for everything setup does not ask about.

Most of what you set in the web UI is not in this file. See Settings in the web UI and the environment.

Where the file is #

OAR_STATE_ROOT moves the whole state folder of a global install (config, data and logs); see Where OAR keeps its files.

COPILOT_WEB_RELAY_CONFIG points the relay at one file, wherever it is, but only where the relay is started without oar's own launcher: node server/server.js, or oar copilot (when the file exists). oar setup, oar start, oar restart and the service always use the install's own config.json, whatever the variable says. In a checkout with no server/config.json, oar copilot creates its file in ~/.config/copilot-remote instead (%LOCALAPPDATA%\copilot-remote on Windows). See Environment variables.

The relay keeps the file readable by its owner only (mode 0600 on macOS and Linux), because it holds the access token in plain text. Treat a copy of it like a password.

Who writes it #

• oar setup writes the token, localhostOnly and port, and keeps every other key as it finds it. A file it creates, or one that lacks them, also gets pollIntervalMs, processingTimeoutMs (600000) and conversationSessionMode. See oar setup and first run.
• The relay writes cliBinaries when you install or update a provider CLI from Settings. It changes only that key. If it cannot read the file as JSON, it refuses to write and keeps the binding for the running process only.
• The relay creates the file when none exists at start-up, with an empty authToken, port 3333, localhostOnly: true, pollIntervalMs and conversationSessionMode. It also removes a features key left over from older releases (see Deprecated, ignored and internal keys).
• You, in any text editor.

Editing it by hand #

The file is one JSON object. Keys you leave out take their defaults, and a nested block such as previews is read as a whole. Edit it, then restart the relay: the relay reads the file once, at start-up. Nothing a running relay holds changes when you save the file. Restart with oar restart (global installs), or with 🌄 Restart web relay in a conversation's ⋯ menu.

• An unknown key is ignored and kept. Setup and the relay's own writes leave it in place.
• Invalid JSON does not stop the relay. It logs Failed to read config.json, using defaults. and runs with the defaults: port 3333, this machine only, and a random token that is new on every start and printed in the log. Your saved token no longer works until you fix the file. A second reader, the one that chooses the data folder, falls back to the default folder. The relay does not touch the broken file.
• A wrong value is handled key by key. The defaults below are what the relay uses when a timer or limit is missing or unusable. The tunnels and the preview lane stay off and log the reason; the relay itself keeps running.
• The command line wins over the file for one run: --token <value> and --port <number> on node server/server.js (oar copilot passes them too; oar start does not) override authToken and port and are never saved to the file. A --port that is not a number from 1 to 65535 is ignored with a warning.

Network and access #

For the first connection, the token and LAN access, see first run.

Turns and timers #

The max turn duration, the background task timeout and the stall watches are not here: see When a turn is stuck.

Restarts and shutdown #

These shape the planned restart of the relay (🌄 Restart web relay). See Restarts and resume. Each timer takes milliseconds; a value of 0 or less, or one that is not a number, uses the default.

Memory Added in 0.9.19 #

Workspace and data #

Provider CLIs #

These matter where the relay talks to the installed Copilot CLI itself, for example to import existing Copilot sessions and to list models. The search looks in the Copilot CLI's package cache (COPILOT_PKG_DIR adds one folder to search first). See GitHub Copilot.

Previews #

The previews block turns on the preview lane: a second listener on its own port and hostname that publishes local dev servers and folders. Setup, hostnames and the front proxy are on the preview tool's page.

If one of these rules fails while previews are on, the relay logs PREVIEW LANE disabled with the reason, leaves the lane off and keeps running.

These environment variables override the matching keys: COPILOT_PREVIEWS_ENABLED (1, true, 0, false), COPILOT_PREVIEWS_PORT, COPILOT_PREVIEWS_BIND_HOST, COPILOT_PREVIEWS_PUBLIC_BASE_URL and COPILOT_PREVIEWS_ALLOWED_TARGET_HOSTS (comma separated).

Tunnels #

Two tunnels can reach the relay from outside your network. They are independent and can run at the same time. Both are off by default, and a managed tunnel that is missing a required value stays off and logs why.

sshTunnel #

A reverse SSH tunnel to a server of yours. See SSH tunnel.

cloudflaredTunnel #

Runs Cloudflare's cloudflared, which you install yourself; OAR ships none. See Cloudflare Tunnel.

Settings in the web UI and the environment #

Settings in the web UI are not in this file. Provider switches and keys, the model lists, the max turn duration, the background task timeout and feature flags are stored in the relay's database, in the data folder. The file holds what the relay needs before the database opens (the data folder, the port, the token) and facts about the machine (CLI paths, tunnels). The one thing the UI writes into the file is cliBinaries. Added in 0.9.17 DeepSeek has no key here either: its API key, base URL and budget are saved from Settings → Providers → DeepSeek into the database.

Environment variables. The full list is on Environment variables. Where a variable exists for a key, the variable wins over the file: COPILOT_WEB_RELAY_DATA_DIR (dataDir), COPILOT_WORKSPACE_ROOT_ALLOW_LIST, COPILOT_CLOUDFLARED_* and COPILOT_PREVIEWS_* (listed in their sections). COPILOT_TUNNEL_MARKER_HEADERS is the exception: its names are added to tunnelMarkerHeaders. The --token and --port options win over both for one run. COPILOT_WEB_RELAY_CONFIG itself is covered under Where the file is.

An example #

All values are made up. Delete the blocks you do not use.

{
  "authToken": "0f3c1a9e-example-token-do-not-copy",
  "port": 3333,
  "localhostOnly": false,
  "remotePath": "",
  "trustProxy": "loopback",
  "allowedOrigins": [],
  "publicHostnames": ["relay.example.com"],
  "tunnelMarkerHeaders": ["x-edge-request-id"],
  "processingTimeoutMs": 600000,
  "maxRequeueRetries": 5,
  "contextIndicatorMode": "bar",
  "workspaceRootAllowList": ["/home/dev/projects", "/srv/sites"],
  "dataDir": "data",
  "cliBinaries": {
    "claude": "/home/dev/.local/bin/claude",
    "grok": "/home/dev/.grok/bin/grok"
  },
  "restartShutdownTimeoutMs": 45000,
  "restartGracefulTimeoutMs": 8000,
  "restartSpawnTimeoutMs": 18000,
  "restartRebindTimeoutMs": 20000,
  "restartReadyCooldownMs": 1000,
  "restartMaxAttempts": 3,
  "restartRetryBackoffMs": [1000, 3000, 7000],
  "previews": {
    "enabled": true,
    "port": 3334,
    "bindHost": "127.0.0.1",
    "allowPublicBind": false,
    "publicBaseUrl": "https://preview.example.com",
    "allowedTargetHosts": [],
    "maxLive": 8
  },
  "sshTunnel": {
    "mode": "managed",
    "required": false,
    "user": "ubuntu",
    "host": "vps.example.com",
    "remotePort": 4444,
    "remoteBind": "loopback",
    "identityFile": "~/.ssh/id_ed25519"
  },
  "cloudflaredTunnel": {
    "mode": "disabled",
    "token": "",
    "binary": "cloudflared",
    "extraArgs": []
  }
}

Deprecated, ignored and internal keys #

If you find one of these in a file, you can leave it or delete it: