Skip to main content

Control what an environment's tools can do

Each execution environment has three policy sections: Tool Access, File Access and Approval Requirements. The platform enforces them before any call reaches your runner, and the runner can't override them.

All three sections apply when you select Save at the top of the environment form. Restrictions take effect at once, because the platform checks every call. Newly allowed tools and changed file paths only reach a connected runner the next time it connects, so restart the runner after loosening anything (for a service on Linux, systemctl --user restart fyai-runner; on any OS, fyai-runner uninstall then fyai-runner install).

Choose the allowed tools​

  1. Go to Platform → Environments and select the environment.
  2. Under Tool Access:
    • Turn Expose all runner tools (wholesale) off to use an allow-list, then tick each tool agents may use.
    • Turn it on to expose everything the runner has.
  3. Select Save.

The checklist shows the tools the runner last announced, and a runner only announces the tools it's allowed. To add a tool that isn't in the list yet:

  1. Turn Expose all runner tools (wholesale) on and select Save.
  2. Restart the runner so it announces every tool it has.
  3. Reload the page and select the environment again. The list now shows every tool.
  4. Turn the switch off, tick the tools you want and select Save.
  5. Restart the runner again so it applies the new list.

If the list says No tool catalogue available yet, the runner hasn't connected. Connect it first.

warning

Expose all runner tools (wholesale) includes shell, which can run any command as the runner's user, and file_write. Prefer an explicit list. Tools relayed from local MCP servers have names like server__tool, and an allow-list must name each one.

Restrict file access​

file_read and file_write only work inside the directories you list. Claude Code runs also default to these directories.

  1. Under File Access, make sure the list is showing (the Unrestricted switch off).
  2. Type a directory, for example /srv/repos or ~/projects, and select Add Path. Repeat as needed. Select the x on a path to remove it.
  3. Select Save.

Paths include everything below them. To allow every directory, add * as a path. Don't rely on the Unrestricted switch: on environments created in the app, saving with it on reverts to no paths.

shell, git, kubectl and the other command tools aren't limited by these paths. If an agent shouldn't touch files outside a directory, don't allow shell.

Require approval for a tool​

  1. Under Approval Requirements, turn No tools require approval off.
  2. Tick the tools that should need approval. Typical choices are shell, file_write, docker and terraform.
  3. Select Save.

When an agent in chat calls a ticked tool, an approval card appears and the tool runs only once someone approves it. A direct call through the API or the FYAI MCP server is refused with a 403, because there is nobody to ask.

Approval for runner tools can also come from elsewhere. If the agent, its team or an Execution environment tool function pins Always require, or your risk appetite requires approval, the card appears even for tools not ticked here. See Agents and Functions.

Limit tools further on the machine​

The machine's owner can tighten some things in ~/.fyai/runner-config.yaml that the platform doesn't control:

  • mcp_servers.<name>.allow_tools / deny_tools: which tools of a relayed MCP server are announced at all
  • claude.allowed_permission_modes, claude.allowed_cwds, claude.max_budget_usd: limits for Claude Code runs
  • browser.allowed_domains: hosts the browser may visit

The local allowed_tools, file_allowed_paths and require_approval_for keys don't restrict anything once the runner connects, because the environment's settings replace them. See the runner reference.