Permissions

Every tool call passes through the permission runtime before it executes. Four things decide the outcome:

1. Whether the tool needs approval at all. Listing, globbing, searching, and reading files in the workspace do not. write_file, edit_file, delete_file, rename_file, copy_file, create_folder, run_command, open_file, install_skill, and vision do, and reaching a path outside the workspace is subject to policy for every file tool.
2. Deny and allow rules saved in your profile, matched against the tool and its target.
3. Session grants created earlier in the session by choosing "Yes, and don't ask again".
4. The permission mode, which decides what happens to a call that no rule or grant resolved.

Once a command is allowed, the sandbox limits what it can do while it runs. That is a separate decision from permission.

Modes

In auto, an unresolved or unavailable automatic review falls back to human approval in interactive mode. In fx ask, unresolved calls stop the run because no human prompt is available.

Change the mode

Inside fx:

/permissions reset switches back to ask and clears the grants collected in this session.

Outside fx, inspect the effective mode and rules:

The mode also comes from permission_mode in ~/.fx/settings.json or the FX_PERMISSION_MODE process override; see Configuration.

Automatic review configuration and cost

Automatic review is active when the effective permission_mode is "auto". Configure it through ~/.fx/settings.json, /permissions auto, or the FX_PERMISSION_MODE=auto process override. Permission rules and session grants are evaluated first, so only eligible unresolved calls reach the reviewer.

Automatic review sends a separate AI Gateway request using the active Gateway credential and team. fx uses openai/gpt-5.4 for the review, independently of the active agent model. There is no public reviewer-model setting, and changing model, FX_MODEL, or the model selected in the shell does not change the reviewer model.

Because review is an additional model request, an unresolved call in auto mode can cost more than the same call in ask mode. A transient failure or invalid response can cause one bounded second review request. Add narrow allow or deny rules when you want known actions settled without an automatic review. See Additional model requests.

When fx asks

Interactive approval prompts have three decisions:

A command approval and a sandbox-widening approval are separate decisions. If an allowed command needs access beyond the active sandbox, fx asks again for that broader access.

Persistent rules

Permission rules are stored in ~/.fx/settings.json, either globally or under the current workspace profile. Project .fx.json files cannot define them.

{
  "permission": {
    "*": "ask",
    "bash": {
      "git *": "allow",
      "git push *": "deny"
    },
    "edit": {
      "docs/*": "allow",
      "*": "deny"
    }
  }
}

Rules use wildcard matching. The last matching rule wins, and workspace rules take precedence over user-global rules.

Manage rules in the interactive shell:

/allowlist view effective
/allowlist local add command "zig build test"
/allowlist user add tool read_file
/allowlist local remove command "zig build test"
/allowlist local reset all

Prefer local rules for repository-specific authority. A user allow rule can apply in every project that does not override it.

Session grants

Choosing "Yes, and don't ask again" creates a live session grant. It is not written to settings and is not restored by fx resume.

Sandbox modes

Permissions decide whether a command may run. The sandbox limits what an allowed command can do after it starts.

• os uses fx's native operating-system sandbox, currently available on macOS. Commands can read files, while writes are restricted to the primary workspace, active additional directories, temporary paths, and required device paths. Outbound network access is allowed; listening on localhost requires separate sandbox authority.
• none adds no fx command isolation. Permission rules still apply, and the host operating system can still deny filesystem or network access.
• auto selects os when the host supports it and otherwise resolves to none. It is accepted in JSON config, while /sandbox sets the explicit os or none mode.

If an allowed command needs broader sandbox access, interactive fx can ask for a separate widening approval. Approving the command itself does not automatically grant that broader access. yolo always uses an effective sandbox of none for the current run without rewriting the saved sandbox setting.

Prompt-free inspection commands

In ask mode, fx can directly execute a narrow native grammar without a prompt: physical pwd, restricted ls, stdin-only wc, restricted literal printf, and pipelines of at most eight stages composed only from those commands.

All Git commands, shell expansion, redirects, writes, network commands, background commands, unsupported options, and other shell syntax remain approval-bearing. Direct output is escaped and capped at 65,536 combined bytes.

If a call is denied or reviewed when you did not expect it, see Troubleshooting.