Configuration

fx separates repository-safe defaults from private user and workspace preferences. Use /settings, /permissions, /sandbox, and /workspace when possible; direct JSON editing is useful for settings that do not have an interactive control.

Files and precedence

For each setting, the highest available source wins:

1. command-line or process override, where supported
2. environment variable
3. matching workspace entry in ~/.fx/settings.json
4. global entry in ~/.fx/settings.json
5. <workspace>/.fx.json
6. built-in default

The settings file is limited to 64 KiB. Unknown JSON keys are ignored, but invalid values in known keys can make a layer unusable and produce a startup diagnostic.

Project configuration

.fx.json accepts exactly four public fields:

{
  "max_agent_steps": 40,
  "max_tool_result_bytes": 131072,
  "context": true,
  "sandbox": "os"
}

"macos" is accepted as a legacy alias for "os". The retired "vercel" and "just-bash" values are rejected.

Profile-only fields such as model, credentials, permission mode and rules, effort, appearance, notifications, update channel, and additional directories are ignored in project config. context_limits is also profile-only.

User profile

A complete representative ~/.fx/settings.json looks like this. Omit values you want fx to resolve from a lower layer or its defaults.

{
  "model": "zai/glm-5.2-fast",
  "permission_mode": "auto",
  "max_agent_steps": 0,
  "max_tool_result_bytes": 65536,
  "first_call_tool_choice": "auto",
  "context": true,
  "context_limits": {
    "skill_catalog_bytes": 16384,
    "project_instructions_total_bytes": 131072
  },
  "fast_mode": false,
  "effort": "auto",
  "sandbox": "none",
  "input_appearance": "tint",
  "slash_menu_categories": true,
  "auto_upgrade": true,
  "update_channel": "stable",
  "startup_scrollback": true,
  "prompt_history": {
    "enabled": true
  },
  "statusLine": {
    "sandbox": false,
    "context": false,
    "session": false
  },
  "notifications": {
    "turn_end": true,
    "attention_required": true,
    "max": false
  },
  "permission": {
    "*": "ask"
  },
  "workspaces": {
    "/absolute/path/to/project": {
      "sandbox": "os",
      "additional_directories": [
        "/absolute/path/to/shared"
      ],
      "permission": {
        "edit": {
          "docs/*": "allow",
          "*": "deny"
        }
      }
    }
  }
}

Agent and model settings

context_limits accepts the keys and byte values listed in Context limits. Permission rules accept "allow", "ask", and "deny"; see Permissions for matching and scope.

permission_mode: "auto" enables automatic review for eligible unresolved calls. fx uses openai/gpt-5.4 as the reviewer. The reviewer model is not a profile, project, environment, or CLI setting. Automatic reviews are additional Gateway requests and can add usage and cost; see Automatic review configuration and cost.

Interface and update settings

fx-managed fields

credential_source and yolo_acknowledged are valid profile fields, but fx manages them through authentication and permission flows. Avoid editing them by hand.

Credential source values are vercel_oidc_token, ai_gateway_api_key, fx_login, and stored_key.

Workspace entries

Keys under workspaces are absolute primary workspace paths. fx saves workspace-local sandbox settings, permission rules, and additional_directories there. An additional-directory list contains at most 16 unique absolute directory paths.

A workspace object is parsed with the same setting schema as the top-level profile and may therefore carry deliberate local overrides, including context_limits and the four project-safe fields. The current interactive controls save model, effort, fast mode, permission mode, appearance, prompt history, status line, notification, and update preferences globally; older workspace copies of model and interface preferences are treated as legacy and may be migrated.

Additional directories extend tool access only. They do not contribute config, AGENTS.md, skills, hooks, Git identity, sessions, or history. See Additional workspaces.

Environment variables

These are the supported user-facing process overrides and runtime controls:

Advanced process controls:

Environment and command-line overrides affect only the current process and are not written back to settings.

Herdr integration

When fx runs inside Herdr, Herdr provides HERDR_SOCKET_PATH and HERDR_PANE_ID. fx then reports its lifecycle state automatically:

idle → working → idle
           └→ blocked: permission, question, or recovery

Reports contain the pane identity, fx session ID, agent label, lifecycle state, and attention reason. Prompts, transcripts, and tool output are not included. Communication stays on Herdr's local Unix socket, and reporting failures never stop the fx session.

Set FX_HERDR=0 or FX_HERDR=false to opt out. You normally do not need to set the two HERDR_* variables yourself.

Inspect effective configuration

Inspect the resolved startup configuration as text or JSON:

Use fx permissions --json for the resolved permission rules and fx workspace --json for active additional directories.

Local state

fx stores private runtime state under ~/.fx/, including settings, the saved Vercel session, sessions, prompt history, usage, traces, recordings, MCP config, and managed skills. On macOS, a stored API key lives in Keychain instead.