---
title: "Configuration"
description: "Reference for fx settings, scopes, defaults, and environment variables."
canonical_url: https://fx.sh/docs/configure-fx/configuration
markdown_url: https://fx.sh/docs/configure-fx/configuration.md
---

# Configuration

Use [`/settings`](https://fx.sh/docs/using-fx/slash-commands.md#inspection-and-settings) to change your preferences in fx, or `fx config set` from a terminal or script:

```bash
fx config set fast_mode on
```

`fx config set` saves a preference in `~/.fx/settings.json` for every workspace and prints where it went; `fx config unset` removes it. Both also remove an older copy of the key from [workspace entries](#workspace-entries), so the change takes effect everywhere. Switches take `true` or `false` (`on` and `off` work too). Permission, model, provider, and account settings keep their own commands, such as `/permissions`, `/model`, `fx provider`, and `fx login`. Edit `~/.fx/settings.json` for the rest, such as `review_model`, `first_call_tool_choice`, `provider_order`, and `context_limits`, and `.fx.json` for shared project defaults. When `fx config` refuses a key, it says what to use instead.

## Files and precedence

| File | Purpose |
| --- | --- |
| `~/.fx/settings.json` | Personal settings and workspace overrides. |
| `<workspace>/.fx.json` | Shared project defaults. |

[MCP servers](https://fx.sh/docs/capabilities/mcp.md) use separate files: `~/.fx/mcp.json` and `<workspace>/.mcp.json`.

To keep a separate profile, set `FX_HOME` to an absolute path. fx then uses that folder in place of `~/.fx` for settings, sessions, and everything else it stores there, and messages name it `$FX_HOME`. For example, `FX_HOME=/tmp/fx-test fx` reads `/tmp/fx-test/settings.json`. `fx status` shows the folder in use. fx creates the folder, and any missing folders above it, on first use, and `FX_HOME` works even when `HOME` isn't set. It must be a folder, not a file. It can't be `/` or your home folder itself, because fx keeps its folder private to your user. The OS keychain is shared between profiles.

For each setting, the highest available source wins:

1. command-line flag, where supported
2. environment variable
3. [`fx ask --config key=value`](https://fx.sh/docs/using-fx/fx-ask.md#override-a-setting-for-one-request), for one request
4. matching workspace entry in `~/.fx/settings.json`
5. global entry in `~/.fx/settings.json`
6. `<workspace>/.fx.json`
7. built-in default

Settings files have a 64 KiB limit. fx ignores unknown keys. A value fx can't use, such as text where a setting takes a number, can make fx skip the rest of that file or workspace entry, keeping only its provider and model choices. fx reports the problem at startup. Run `fx doctor` to list unknown keys, such as a misspelled setting, with the closest known key. It also lists older names, such as `statusLine` and a saved `permission_mode` of `yolo`, which fx still reads until 0.0.18.

If other users can write to `~/.fx` or `~/.fx/settings.json`, fx removes their write access at startup and loads the settings, with a note asking you to check `settings.json` if you didn't write it yourself. `fx ask` and other commands print the same note on stderr. If fx can't change the permissions, such as on a folder you don't own, it skips those settings.

### Check settings in your editor

Editors that read JSON Schema, such as VS Code, can complete and check settings files. Add a `$schema` key to the top of the file:

```json
{
  "$schema": "https://fx.sh/schemas/settings.json"
}
```

Use `https://fx.sh/schemas/fx.json` in a project `.fx.json`. The editor then flags unknown keys, wrong types, and values fx doesn't accept, and marks older names as deprecated. fx ignores `$schema` when it reads the file. `fx config schema` prints the schema for the installed version, and `fx config schema --project` prints the one for `.fx.json`.

## Project configuration

Create `.fx.json` in the directory where you run fx, or add these fields to the existing file:

```json
{
  "max_agent_steps": 40,
  "max_tool_result_bytes": 131072
}
```

| Field | Description | Type and values | Default |
| --- | --- | --- | --- |
| `max_agent_steps` | Maximum agent steps per turn; `0` means unlimited. | Non-negative integer | `0` |
| `max_tool_result_bytes` | Tool output budget in model context; saved results can be larger. | Integer of at least `1024` | `65536` |
| `context` | Load [project instructions](https://fx.sh/docs/configure-fx/project-instructions.md). | Boolean | `true` |
| `provider_order` | Preferred AI Gateway providers, in order. | Array of up to 8 provider slugs | No preference |
| `provider_strict` | Restrict Gateway requests to `provider_order`. | Boolean | `false` |

Only the fields above apply in `.fx.json`; fx ignores any other setting there and warns about it. Keep personal settings, including models and permissions, in `~/.fx/settings.json`. See [Model routing](https://fx.sh/docs/configure-fx/models.md#ai-gateway-routing) for `provider_order` and `provider_strict`.

## User profile

Add these fields to `~/.fx/settings.json` to collapse tool output and turn off generated conversation titles:

```json
{
  "collapse_tool_calls": true,
  "session_titles": false
}
```

Restart fx after editing a settings file by hand. The profile also accepts the [project settings](#project-configuration) listed above.

### Agent and model settings

| Field | Description | Values and default |
| --- | --- | --- |
| `provider` | Service used for model requests. | `"gateway"`, `"codex"`, `"grok"`, or a configured connection name. Default: `"gateway"`. |
| `providers` | Named [custom model connections](https://fx.sh/docs/configure-fx/custom-model-connections.md). | Object stored only at the top level of the private profile. |
| `models` | Saved model ID for each provider or connection. | Object keyed by provider, such as `{"gateway": "moonshotai/kimi-k3"}`. |
| `permission_mode` | How fx handles tool calls that need permission. | `"ask"`, `"auto"`, or `"full-access"`; legacy `"yolo"` is also accepted. Default: `"auto"`. |
| `first_call_tool_choice` | Tool choice for the first model request of each turn; required vision fallback takes precedence. | `"auto"` or `"none"`. Default: `"auto"`. |
| `review_model` | AI Gateway reviewer used by Auto mode. | An AI Gateway model ID or `"typesafeai/jev"`. See [review models](https://fx.sh/docs/configure-fx/permissions.md#auto-mode). |
| `fast_mode` | Use faster inference when supported. | Boolean. Default: `false`. |
| `ultrafast_mode` | Request the higher-priced [OpenAI Ultrafast tier](https://fx.sh/docs/configure-fx/models.md#ultrafast-mode) for an eligible AI Gateway model. Cannot be set by project `.fx.json`. | Boolean. Default: `false`. |
| `effort` | Reasoning effort for the selected model. | `"auto"` or an effort name supported by the model; `null` resets to auto. Default: `"auto"`. |
| `auto_compact_percent` | Start automatic compaction at this percentage of usable input capacity. | Integer from `10` to `80`. Default: `80`. |
| `tool_placement` | Which built-in tools fx sends directly and which it lists in [toolbox](https://fx.sh/docs/capabilities/tools.md#toolbox). Cannot be set by project `.fx.json`. | Object mapping a tool name to `"toolbox"` or `"direct"`. Default: `install_skill` in toolbox, the rest direct. |
| `cache_warming` | Keep a waiting Claude conversation's [prompt cache](https://fx.sh/docs/using-fx/usage-and-costs.md#cache-warming) alive through AI Gateway for up to 30 minutes after its last request. | Boolean. Default: `true`. |

For `context_limits`, see [Context limits](https://fx.sh/docs/configure-fx/context-limits.md). For `permission` rules, see [Permissions](https://fx.sh/docs/configure-fx/permissions.md). For `skill_symlink_authorities`, see [Skills](https://fx.sh/docs/capabilities/skills.md#discovery-roots).

### Interface and update settings

| Field | Description | Values and default |
| --- | --- | --- |
| `slash_menu_categories` | Show command categories and skill sources in search results. | Boolean. Default: `true`. |
| `auto_upgrade` | Download and install updates in the background; press ctrl+g to reload. | Boolean. Default: `true`. |
| `update_channel` | Release channel used for updates. | `"stable"` or `"dev"`. Default: `"stable"`. |
| `startup_scrollback` | Restore terminal output at startup. | Boolean. Default: `true`. |
| `collapse_tool_calls` | Show a summary for each tool-call group. | Boolean. Default: `false`. |
| `session_titles` | Generate a title from the first prompt. | Boolean. Default: `true`. |
| `theme` | Built-in or custom [terminal theme](https://fx.sh/docs/configure-fx/themes.md). | `"light"`, `"dark"`, or the name of a file in `~/.fx/themes/`, without `.json`. Default: follows the terminal. |
| `prompt_history.enabled` | Save prompts and slash commands for input history. | Boolean. Default: `true`. |
| `status_line.context` | Show context usage in the footer. | Boolean. Default: `false`. |
| `status_line.session` | Show the session title in the footer. | Boolean. Default: `false`. |
| `status_line.workspace` | Show the workspace path and Git branch. | Boolean. Default: `false`. |
| `sound.turn_end` | Play a sound when a turn finishes. | Boolean. Default: `true` on macOS, `false` elsewhere. |
| `sound.attention_required` | Play a sound when fx needs your attention. | Boolean. Default: `true` on macOS, `false` elsewhere. |
| `sound.max` | Enable extra interaction sounds when sound is on. | Boolean. Default: `false`. |

Press ctrl+o to see collapsed tool output in Full detail. [Automatic titles](https://fx.sh/docs/using-fx/sessions.md#session-titles) make a separate model request.

### Terminal themes

fx follows the terminal's light or dark mode by default. Set `theme` to `"light"`, `"dark"`, or the name of a JSON file in `~/.fx/themes/`. See [Themes](https://fx.sh/docs/configure-fx/themes.md) for the file format, VS Code themes, and troubleshooting.

## Workspace entries

To override a setting for one project, add its absolute path under `workspaces` in `~/.fx/settings.json`:

```json
{
  "max_agent_steps": 40,
  "workspaces": {
    "/path/to/project": {
      "max_agent_steps": 80
    }
  }
}
```

This allows 80 agent steps per turn in that project and 40 elsewhere. Workspace settings override global and project settings.

fx also stores local permission rules here, along with keys it reads only inside a workspace entry: `additional_directories`, which `fx workspace` manages for [additional directories](https://fx.sh/docs/configure-fx/additional-workspaces.md), and the project MCP server approvals `enabledMcpjsonServers`, `disabledMcpjsonServers`, and `enableAllProjectMcpServers`, which `fx mcp approve` and `fx mcp reject` manage. Custom connection definitions (`providers`) and `$schema` belong at the top level. Model and interface changes made through fx's menus are saved globally.

## Environment variables

Environment variables override saved settings for the current process. For example:

```bash
FX_MAX_AGENT_STEPS=20 fx
```

| Variable | Description |
| --- | --- |
| `AI_GATEWAY_API_KEY` | Authenticate with a Vercel AI Gateway API key. |
| `VERCEL_OIDC_TOKEN` | Authenticate in a Vercel-managed environment. |
| `FX_PROVIDER` | Select a built-in provider or custom connection for this process. |
| `FX_MODEL` | Override the model for this process. |
| `FX_ULTRAFAST` | Request [Ultrafast](https://fx.sh/docs/configure-fx/models.md#ultrafast-mode) with `1`, `true`, `on`, or `yes`; disable with `0`, `false`, `off`, or `no`. Values are trimmed and case-insensitive; invalid values fail startup. CLI flags take precedence. |
| `FX_REVIEW_MODEL` | Override the AI Gateway permission reviewer for this process. |
| `TYPESAFE_API_KEY` | Call TypeSafe directly when the review model is `typesafeai/jev`. |
| `FX_PROVIDER_ORDER` | Set comma-separated AI Gateway provider slugs in preference order. |
| `FX_PROVIDER_STRICT` | Restrict Gateway routing to the configured provider order with `1`, `true`, `on`, or `yes`; lift the restriction with `0`, `false`, `off`, or `no`. |
| `FX_PERMISSION_MODE` | Override with `ask`, `auto`, or `full-access`; legacy `yolo` is also accepted. |
| `FX_MAX_AGENT_STEPS` | Override the agent step limit. |
| `FX_AUTO_COMPACT_PERCENT` | Override `auto_compact_percent` with a whole number from 10 to 80; other values are ignored. |
| `FX_THEME` | Select `light`, `dark`, or a custom theme for this process. |
| `FX_SOUND` | Override all three `sound` settings: `off`, `0`, or `false` turns every sound off, `max` turns every sound on, and another value, such as `on`, turns on the turn-end and attention sounds. |
| `FX_AUTO_UPGRADE=0` | Disable automatic upgrades for the process; `false` works too. |
| `FX_NO_OPEN_BROWSER=1` | Print authentication URLs instead of opening a browser. |
| `FX_HOME` | Use this absolute folder in place of `~/.fx` for settings, sessions, and other state. |
| `NO_COLOR` | Set to any non-empty value to turn color off in help, `fx ask`, and the interactive session. The interactive session keeps bold, dim, and reverse text; help prints no styling at all. |
| `TERM=dumb` | Turn color off in help and `fx ask`. The interactive session needs cursor movement, so `fx` exits and suggests `fx ask` instead. |

### Diagnostics

Use these controls when investigating a problem:

| Variable | Description |
| --- | --- |
| `FX_DEBUG_RECORD=1` | Write an automatic private terminal recording under `~/.fx/recordings/`. |
| `FX_DEBUG_RECORD_SILENT_BANNER=1` | Hide the recording notice from the inline transcript while keeping it in Ctrl-O. |
| `FX_RECORD` | Write a terminal recording to an explicit path. |
| `FX_RECORD_INPUT=1` | Include raw terminal input events in a recording. |
| `FX_TRACE=1` | Write a trace to the default private trace path. |
| `FX_TRACE_LOG` | Write a trace to an explicit path; relative paths resolve from the primary workspace. |
| `FX_TRACE_SCOPES` | Limit traces to an exact comma-separated list of scopes. |
| `FX_TRACE_STDERR=1` | Write trace lines to stderr, alone or alongside a trace file. |
| `FX_SYNC_UPDATES` | Set `on` or `off` to troubleshoot terminal synchronized updates. |
| `FX_DISABLE_KEYCHAIN=1` | Disable the native macOS API-key store; `fx login vercel --api-key` cannot save a key while set. |
| `FX_HERDR=0` | Disable automatic Herdr lifecycle reporting. |

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

## Herdr integration

When launched inside Herdr, fx names its pane `fx` and reports whether it is idle, working, or waiting for input. A waiting report says why: a permission request, a question, or a request only you can continue, such as one that ran out of credits. With several [instances](https://fx.sh/docs/using-fx/instances.md) open, it reports the busiest one: waiting for input over working, and working over idle. Herdr supplies the local socket and pane ID through `HERDR_SOCKET_PATH` and `HERDR_PANE_ID`. Reports include the session state and session ID, but no prompts or tool output. If Herdr doesn't answer, fx keeps running without the reports. Set `FX_HERDR=0` or `FX_HERDR=false` to disable reporting.

<span id="inspect-effective-configuration" />

## Check which settings fx is using

Show the settings in effect for this run:

```bash
fx status
```

```bash
fx status --json
```

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

To see what each settings file sets, list the values in order from lowest to highest precedence:

```bash
fx config list --show-origin
```

Each line starts with where the value comes from, then `key=value`, with nested keys in dotted form such as `status_line.context`. Values from a settings file or workspace entry come first. A set environment variable that overrides a setting comes last, as `env:FX_MAX_AGENT_STEPS`, because it overrides the files; a value fx ignores isn't listed. When a key appears more than once, the last line is the one fx uses. `fx config get <key>` prints the value a run uses, including the default when nothing sets it; with `--show-origin`, it names where that value comes from, or `default`. If fx rejects or ignores what a file sets, `get` shows the value fx uses instead and prints the same warning `fx status` does. Command-line flags can still override it for one run.

Add `--global` to `list` or `get` to read only the global settings in `~/.fx/settings.json`, or `--workspace` to read only this workspace's entry. `set` and `unset` don't take `--workspace`, because they change a preference for every workspace.

<span id="fx-managed-fields" />

## Compatibility

fx still reads the older `model`, `codex_model`, and `grok_model` keys. Saving a model moves it under `models`.

fx saves full access as `"permission_mode": "full-access"` and still reads the older `"yolo"` until fx 0.0.18. fx manages `yolo_acknowledged`, `credential_source`, and `fast_mode_model_bound` when you change permissions, sign in, or turn Fast mode on or off.

fx still reads the older `statusLine` and `notifications` keys until fx 0.0.18. Saving a status line or sound setting moves them to `status_line` and `sound`. If a file sets both spellings, the newer key wins, and `fx doctor` names the older one to remove. `fx config` accepts either spelling.

fx no longer supports `skill_match_fuzzy`. A `~/.fx/settings.json` that still sets it is ignored, and fx prints `remove skill_match_fuzzy` until you delete the key. Skills load only when you invoke them or the agent opens them with toolbox.

fx ignores the retired `input_appearance`, `maxxing_mode`, `sandbox`, and `web_fetch_worker_model` keys without a warning, and editors mark them as deprecated. You can delete them.

## Local state

See [Data and privacy](https://fx.sh/docs/using-fx/data-and-privacy.md) for saved conversations, credentials, and other local state.

---

[Browse all fx documentation](https://fx.sh/llms.txt)
