Configuration

Use /settings to change your preferences in fx, or fx config set from a terminal or script:

$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, 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

FilePurpose
~/.fx/settings.jsonPersonal settings and workspace overrides.
<workspace>/.fx.jsonShared project defaults.

MCP servers 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, 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:

{
  "$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:

{
  "max_agent_steps": 40,
  "max_tool_result_bytes": 131072
}
FieldDescriptionType and valuesDefault
max_agent_stepsMaximum agent steps per turn; 0 means unlimited.Non-negative integer0
max_tool_result_bytesTool output budget in model context; saved results can be larger.Integer of at least 102465536
contextLoad project instructions.Booleantrue
provider_orderPreferred AI Gateway providers, in order.Array of up to 8 provider slugsNo preference
provider_strictRestrict Gateway requests to provider_order.Booleanfalse

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 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:

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

Restart fx after editing a settings file by hand. The profile also accepts the project settings listed above.

Agent and model settings

FieldDescriptionValues and default
providerService used for model requests."gateway", "codex", "grok", or a configured connection name. Default: "gateway".
providersNamed custom model connections.Object stored only at the top level of the private profile.
modelsSaved model ID for each provider or connection.Object keyed by provider, such as {"gateway": "moonshotai/kimi-k3"}.
permission_modeHow fx handles tool calls that need permission."ask", "auto", or "full-access"; legacy "yolo" is also accepted. Default: "auto".
first_call_tool_choiceTool choice for the first model request of each turn; required vision fallback takes precedence."auto" or "none". Default: "auto".
review_modelAI Gateway reviewer used by Auto mode.An AI Gateway model ID or "typesafeai/jev". See review models.
fast_modeUse faster inference when supported.Boolean. Default: false.
ultrafast_modeRequest the higher-priced OpenAI Ultrafast tier for an eligible AI Gateway model. Cannot be set by project .fx.json.Boolean. Default: false.
effortReasoning effort for the selected model."auto" or an effort name supported by the model; null resets to auto. Default: "auto".
auto_compact_percentStart automatic compaction at this percentage of usable input capacity.Integer from 10 to 80. Default: 80.
tool_placementWhich built-in tools fx sends directly and which it lists in 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_warmingKeep a waiting Claude conversation's prompt cache alive through AI Gateway for up to 30 minutes after its last request.Boolean. Default: true.

For context_limits, see Context limits. For permission rules, see Permissions. For skill_symlink_authorities, see Skills.

Interface and update settings

FieldDescriptionValues and default
slash_menu_categoriesShow command categories and skill sources in search results.Boolean. Default: true.
auto_upgradeDownload and install updates in the background; press ctrl+g to reload.Boolean. Default: true.
update_channelRelease channel used for updates."stable" or "dev". Default: "stable".
startup_scrollbackRestore terminal output at startup.Boolean. Default: true.
collapse_tool_callsShow a summary for each tool-call group.Boolean. Default: false.
session_titlesGenerate a title from the first prompt.Boolean. Default: true.
themeBuilt-in or custom terminal theme."light", "dark", or the name of a file in ~/.fx/themes/, without .json. Default: follows the terminal.
prompt_history.enabledSave prompts and slash commands for input history.Boolean. Default: true.
status_line.contextShow context usage in the footer.Boolean. Default: false.
status_line.sessionShow the session title in the footer.Boolean. Default: false.
status_line.workspaceShow the workspace path and Git branch.Boolean. Default: false.
sound.turn_endPlay a sound when a turn finishes.Boolean. Default: true on macOS, false elsewhere.
sound.attention_requiredPlay a sound when fx needs your attention.Boolean. Default: true on macOS, false elsewhere.
sound.maxEnable extra interaction sounds when sound is on.Boolean. Default: false.

Press ctrl+o to see collapsed tool output in Full detail. Automatic 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 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:

{
  "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, 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:

$FX_MAX_AGENT_STEPS=20 fx
VariableDescription
AI_GATEWAY_API_KEYAuthenticate with a Vercel AI Gateway API key.
VERCEL_OIDC_TOKENAuthenticate in a Vercel-managed environment.
FX_PROVIDERSelect a built-in provider or custom connection for this process.
FX_MODELOverride the model for this process.
FX_ULTRAFASTRequest Ultrafast 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_MODELOverride the AI Gateway permission reviewer for this process.
TYPESAFE_API_KEYCall TypeSafe directly when the review model is typesafeai/jev.
FX_PROVIDER_ORDERSet comma-separated AI Gateway provider slugs in preference order.
FX_PROVIDER_STRICTRestrict Gateway routing to the configured provider order with 1, true, on, or yes; lift the restriction with 0, false, off, or no.
FX_PERMISSION_MODEOverride with ask, auto, or full-access; legacy yolo is also accepted.
FX_MAX_AGENT_STEPSOverride the agent step limit.
FX_AUTO_COMPACT_PERCENTOverride auto_compact_percent with a whole number from 10 to 80; other values are ignored.
FX_THEMESelect light, dark, or a custom theme for this process.
FX_SOUNDOverride 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=0Disable automatic upgrades for the process; false works too.
FX_NO_OPEN_BROWSER=1Print authentication URLs instead of opening a browser.
FX_HOMEUse this absolute folder in place of ~/.fx for settings, sessions, and other state.
NO_COLORSet 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=dumbTurn 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:

VariableDescription
FX_DEBUG_RECORD=1Write an automatic private terminal recording under ~/.fx/recordings/.
FX_DEBUG_RECORD_SILENT_BANNER=1Hide the recording notice from the inline transcript while keeping it in Ctrl-O.
FX_RECORDWrite a terminal recording to an explicit path.
FX_RECORD_INPUT=1Include raw terminal input events in a recording.
FX_TRACE=1Write a trace to the default private trace path.
FX_TRACE_LOGWrite a trace to an explicit path; relative paths resolve from the primary workspace.
FX_TRACE_SCOPESLimit traces to an exact comma-separated list of scopes.
FX_TRACE_STDERR=1Write trace lines to stderr, alone or alongside a trace file.
FX_SYNC_UPDATESSet on or off to troubleshoot terminal synchronized updates.
FX_DISABLE_KEYCHAIN=1Disable the native macOS API-key store; fx login vercel --api-key cannot save a key while set.
FX_HERDR=0Disable 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 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.

Check which settings fx is using

Show the settings in effect for this run:

$fx status
$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:

$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.

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 for saved conversations, credentials, and other local state.