config.json

Reference for ~/.fabric-agent/config.json — app-wide settings, workspace list, LLM connections, defaults, and migration from legacy formats.

Fabric Agents' global configuration lives in a single file:

~/.fabric-agent/config.json

It holds your workspace list, LLM connections, default model and thinking level, UI preferences like theme and keyboard shortcuts, and a handful of feature flags.

Most fields are set through the Settings UI, but the file is plain JSON — edit it directly if you prefer, or commit a copy for version control / backup.

Where fields come from

User-editable (settings, theme, defaults, shortcuts) — set via Settings UI or by editing JSON.
Auto-written by the app — activeWorkspaceId, activeSessionId, timestamps.
Migrated automatically — legacy fields from older versions get upgraded on first launch and then removed.

Full schema

Workspaces and active selection

Field	Type	Purpose
`workspaces`	`Workspace[]`	Known workspace entries: `id`, `name`, `rootPath`, `createdAt`.
`activeWorkspaceId`	`string \| null`	Workspace currently focused in the primary window. Auto-written.
`activeSessionId`	`string \| null`	Active session in the active workspace. Auto-written.

LLM connections

Field	Type	Purpose
`llmConnections`	`LlmConnection[]`	Array of configured providers. See LLM connections for the full schema.
`defaultLlmConnection`	`string`	`slug` of the default connection for new sessions.

Defaults

Field	Type	Default	Purpose
`defaultThinkingLevel`	`"off" \| "low" \| "medium" \| "high" \| "max"`	`"medium"`	Thinking level for new sessions.
`permissionModeDefaults`	`"safe" \| "ask" \| "allow-all"`	`"ask"`	Permission mode for new sessions.

Per-workspace defaults live in {workspace}/config.json under defaults and override the global values.

UI and input

Field	Type	Default	Purpose
`colorTheme`	string	`"default"`	Preset theme ID or custom theme filename. See Themes.
`sendMessageKey`	`"enter" \| "cmd-enter"`	`"enter"`	Keyboard shortcut to send a message.
`autoCapitalisation`	boolean	`true`	Auto-capitalise the first letter of chat messages.
`spellCheck`	boolean	`false`	Enable spell-check in the input.
`notificationsEnabled`	boolean	`true`	Desktop notifications on session events.

System behaviour

Field	Type	Default	Purpose
`keepAwakeWhileRunning`	boolean	`false`	Prevent the system from sleeping while a session is processing.
`browserToolEnabled`	boolean	`true`	Enable the built-in Chromium browser tool.
`richToolDescriptions`	boolean	`true`	Include the `_intent` and rich action metadata in tool calls — slightly more verbose but much easier to audit.
`extendedPromptCache`	boolean	`false`	Use the 1-hour prompt cache TTL instead of the default 5 minutes.
`enable1MContext`	boolean	`true`	Enable 1M-token context window on models that support it.

Updates

Field	Type	Default	Purpose
`updateChannel`	`"stable" \| "pre-release"`	`"stable"`	Which channel auto-update checks against.
`dismissedUpdateVersion`	string	–	Version string the user chose to skip.

Network and OS integration

Field	Type	Purpose
`networkProxy`	`NetworkProxySettings`	HTTP / HTTPS proxy configuration for corporate networks.
`gitBashPath`	string	Windows only — path to `bash.exe`. Used by skills and automations that shell out.

Server mode (embedded server)

Field	Type	Purpose
`serverConfig`	`ServerConfig`	Internal — the embedded server's bind host, port, and token. Auto-written; don't edit by hand.

Onboarding state

Field	Type	Purpose
`setupDeferred`	boolean	`true` if the user picked "Set up later" during onboarding. Skips the prompt on next launch.

A realistic example

{
  "workspaces": [
    {
      "id": "personal",
      "name": "Personal",
      "rootPath": "~/.fabric-agent/workspaces/personal",
      "createdAt": 1704067200000
    },
    {
      "id": "my-app",
      "name": "My App",
      "rootPath": "~/code/my-app",
      "createdAt": 1710000000000
    }
  ],
  "activeWorkspaceId": "my-app",
  "activeSessionId": "260420-swift-river",

  "llmConnections": [
    {
      "slug": "anthropic-api",
      "name": "Anthropic (API Key)",
      "providerType": "anthropic",
      "authType": "api_key",
      "defaultModel": "claude-opus-4-8",
      "createdAt": 1704067200000
    }
  ],
  "defaultLlmConnection": "anthropic-api",

  "defaultThinkingLevel": "medium",
  "colorTheme": "default",
  "sendMessageKey": "enter",
  "notificationsEnabled": true,
  "keepAwakeWhileRunning": false,
  "browserToolEnabled": true,
  "richToolDescriptions": true,
  "extendedPromptCache": false,
  "enable1MContext": true,
  "updateChannel": "stable"
}

Migration

On startup, Fabric Agents converts older config shapes to the current one, then removes the legacy fields:

Legacy field	Migrated to	Notes
`authType` (string at the top level)	`llmConnections[0].authType`	Old single-provider apps.
`anthropicBaseUrl`	`llmConnections[*].baseUrl`	Only when targeting Anthropic.
`customModel`, `model`	`llmConnections[*].defaultModel`	Per-connection model hints.
`type: "openai"` on a connection	`providerType: "pi"` with appropriate `piAuthProvider`	OpenAI-family providers now route through the Pi SDK.
Standalone `bedrock` / `vertex` connections	`providerType: "pi"` with `piAuthProvider` set	AWS / GCP Anthropic endpoints.

Migrations are non-blocking — failures are logged and the old config continues to work.

Editing safely

A few tips if you edit this file directly:

Back up before big changes. cp ~/.fabric-agent/config.json ~/.fabric-agent/config.json.bak.
Close the app first. The running app holds the config in memory and may overwrite your edits on next auto-save.
Never paste credentials here. API keys, OAuth tokens, and refresh tokens live in the OS keychain (macOS / Windows) or encrypted credential store (~/.fabric-agent/credentials/ on Linux). config.json only references connections by slug.

Preferences — ~/.fabric-agent/preferences.json (name, timezone, bio).
LLM connections — the llmConnections[] schema in detail.
Environment variables — env vars that override config values at runtime.

On this page