atrium — Docs
docs/reference/configuration.md

Configuration reference: config.json and Settings

Common config.json keys, accepted values, and the Settings pages that manage them.

atrium's user configuration lives in ~/.atrium/config.json (%USERPROFILE%\.atrium\config.json on Windows). The file is atomically written on every change and restricted to its owner. Dev instances use their own data directories.

Most keys are editable via the Settings dialog with live previews. Hand-editing is supported; atrium watches the file and reloads on change. Unknown keys are preserved in an internal extra bucket so future schema additions do not break older configs.

Top-level shape

{
  "theme": "atrium",
  "terminal": { ... },
  "markdown_editor": { ... },
  "updates": { ... },
  "diagnostics": { ... },
  "worktree": { ... },
  "telemetry": { ... },
  "keybindings": { ... },
  "lspServers": { ... },
  "adapterEnvVars": { ... }
}

theme

String. Either "auto" (follow system light/dark) or the exact name of a built-in or custom theme (for example "atrium", "dracula", "my-theme-custom").

UI: Settings → Theme.

terminal

Shared code typography plus terminal-only appearance. See Appearance for the UI.

{
  "fontFamily": "Menlo, monospace",
  "fontSize": 11,
  "lineHeight": 1.2,
  "letterSpacing": 0,
  "fontLigatures": false,
  "cursorStyle": "block",
  "cursorBlink": true,
  "scrollback": 10000,
  "padding": 8,
  "backgroundOpacity": 1.0
}
  • cursorStyle — "block", "underline", or "bar".
  • backgroundOpacity — 0.0 (transparent) to 1.0 (opaque).
UI: Settings → Terminal.

markdown_editor

Markdown editor pane defaults.

{
  "defaultFont": "Default",
  "fontSize": 14,
  "textAlign": "left",
  "bookView": true,
  "bookViewWidth": "8.5in",
  "bookViewMargin": "0.5in",
  "defaultViewMode": "rte",
  "imagePasteFolder": "media"
}
  • textAlign — "left" / "center" / "right" / "justify".
  • defaultViewMode — "rte" or "source".
  • bookViewWidth and bookViewMargin — dimensions stored as strings; the toolbar edits them in inches.
  • imagePasteFolder — destination relative to the document for pasted images; an empty string saves beside the document.
UI: the Markdown pane's rich-text formatting toolbar and More options menu control font, alignment, and book view. The pane header's view-mode toggle also updates defaultViewMode for new panes. Rich-text appearance changes apply immediately; source mode uses the shared code typography settings.

updates

Update check behavior.

{
  "checkOnLaunch": true,
  "autoInstall": false,
  "channel": "early-access",
  "checkIntervalHours": 6
}
  • channel — "early-access" is the compatibility key used by today's public beta. "stable" and "beta" are planned.
UI: Settings → Updates.

diagnostics

Performance instrumentation. Off by default.

{
  "enabled": false,
  "captureLongTasks": true,
  "captureRenderStats": true,
  "captureIpcTimings": true,
  "captureTerminalStats": true,
  "captureMemoryStats": true,
  "flushIntervalMs": 30000
}

Traces are kept in-memory and flushed to ~/.atrium/diagnostics/ on interval. UI: Settings → Diagnostics.

worktree

Defaults for worktree creation.

{
  "defaultLocationPattern": "~/worktrees/{repo}/{branch}",
  "postCreateCommands": ["pnpm install"]
}
  • defaultLocationPattern — path template. {repo} and {branch} are substituted.
  • postCreateCommands — shell commands to run in the newly created worktree. Run sequentially.

telemetry

Three flags control telemetry. This example leaves analytics off:

{
  "enabled": true,
  "analyticsOptIn": false,
  "coreTelemetryDisclosed": false
}
  • enabled — master kill-switch. When false, atrium sends nothing.
  • analyticsOptIn — user opted into product analytics.
  • coreTelemetryDisclosed — user has acknowledged the core telemetry disclosure.
  • internal — marks a test machine; its events carry internal: true so dashboards can leave it out. Not a consent choice. ATRIUM_TELEMETRY_INTERNAL=1 does the same without editing the file.
See Telemetry for what is collected and when. The usage-data toggle is in Settings → Privacy & data.

keybindings

Map of chord → action override. See Keybindings for the action types.

{
  "cmd+d": { "action": "split-horizontal" },
  "shift+enter": { "action": "send-text", "text": "\n" },
  "alt+cmd+1": {
    "action": "uri-command",
    "command": "atrium://commands/launcher.open?pane=$FOCUS"
  },
  "cmd+b": null
}

null removes a default binding. Chords use the modifier order alt+cmd+ctrl+shift; on Windows, cmd represents the primary Ctrl key. UI: Settings → Keyboard.

lspServers

Override LSP server commands per language. Server IDs match atrium's bundled lsp-servers.toml manifest.

{
  "typescript": { "command": "/opt/homebrew/bin/typescript-language-server" },
  "rust-analyzer": { "command": "~/.cargo/bin/rust-analyzer" }
}

UI: Settings → Tools → LSP servers.

adapterEnvVars

Environment variables applied to panes running a given adapter. See Adapter environment.

{
  "claude-code": {
    "CLAUDE_CODE_NO_FLICKER": "1"
  },
  "codex": {
    "OPENAI_API_KEY": "sk-..."
  }
}

UI: Settings → Tools → [adapter] → Environment variables.

CLI access

Most scalar keys are reachable from the CLI.

atrium config get terminal.fontSize
atrium config set terminal.fontSize 13
atrium config set markdown_editor.bookViewEnabled true
atrium config set telemetry.analyticsOptIn false

set auto-detects the value type (integer, float, boolean, string). Nested object values (for example adapterEnvVars.claude-code) are best edited in the file or the UI directly.

Manage Tailscale from Settings → Remote access → Network. config set refuses the Tailscale choice because changing it also needs to update the running connection. Manage custom API providers in Settings → Providers so secrets go into the credential store rather than ordinary config or environment text.

Permissions

  • ~/.atrium/config.json — 0600 (owner read/write only).
  • ~/.atrium/ itself and most subdirectories — 0700.
The file is atomically written, so a crash mid-save cannot leave a partial config. Older snapshots are not kept automatically; if you hand-edit and break the file, atrium will either log a parse error and start with defaults, or refuse to persist new changes until you fix it.