Sandbox a coding agent on Linux and macOS

Use Workspace when a coding agent should edit its folder but not have unrestricted command access to your machine. Use Read-only to inspect a project without allowing file edits. Full access removes the command sandbox and runs commands as you.

These are the local Fungi Agent’s permissions, implemented by Truffle with Cordyceps’ native tools. They do not change Claude Code’s local permissions or the permissions of a remote Oyster App.

Before you start

Install the fungi command outside your project folder and sign in to a model provider. Run the examples from the project you want the Agent to inspect. The local command sandbox uses bubblewrap (bwrap) on Linux and Seatbelt on macOS.

Select a sandboxed mode explicitly when containment is required. If its sandbox is unavailable, that selected mode refuses rather than running the command unsandboxed.

1. Choose the mode

Start in Workspace:

TERMINAL

fungi --workspace

Or start in Read-only:

TERMINAL

fungi --read-only

The mode determines what local commands can write and reach:

Mode	Linux	macOS
Workspace	Writes the Agent’s folder and temporary files. Selected existing package caches can also be writable. Commands can use the network and ssh-agent.	Writes the Agent’s folder and temporary files. No command network, writable package caches or ssh-agent access.
Read-only	Writes only temporary files. No project or package-cache writes, command network or ssh-agent access.	Writes only temporary files. No project or package-cache writes, command network or ssh-agent access.
Full access	Commands run as your OS user without the sandbox, with your files, network and credentials.	Commands run as your OS user without the sandbox, with your files, network and credentials.

Workspace makes existing local Git administration read-only, including the Git directories of linked worktrees. This protects those local paths, not the remote’s branches. On Linux, writable package caches come from the host environment, not project settings; Fungi’s own cache stays protected.

Read-only also refuses the Agent’s file edits, patches and writes. It asks the Agent to switch to Workspace to edit rather than offering approval for a file edit.

To deliberately start without the sandbox:

TERMINAL

fungi --full-access
# --yolo selects the same mode.

Do not use Full access merely to make a sandbox refusal disappear. Diagnose the reported installation or platform problem first.

2. Inspect permissions in the conversation

Type /permissions to see the selected Agent’s mode and the project’s saved Always-allow rules. Enter keeps the current mode. Switching to Full access needs a separate confirmation, which defaults to keeping current permissions.

The mode belongs to the Agent. Saved rules are shared by Workspace Agents in the same project; Read-only Agents do not use those rules.

3. Approve one command when it needs more access

A sandboxed Agent can ask to run a command outside the sandbox. Review the command, its working directory and its reason before approving. Approval runs that command once; answering the same request again does not run it twice.

Changing protected local Git administration requires an approved sandbox escape or a matching saved rule. That filesystem boundary is not a push-approval policy.

Linux Workspace does not prevent pushes. Commands can use the network and ssh-agent. A git push can update a remote without approval even when .git is read-only; only the subsequent local tracking-ref update may fail. Not saving or removing a git push rule does not stop a push that can run inside the sandbox.

Read-only disables command network on both platforms; macOS Workspace also disables it. These restrictions apply to sandboxed commands, not approved escapes or Full access. Enforce remote write permissions separately rather than relying on a read-only local .git directory.

An approved command runs as you. Git hooks can execute under that grant. An Agent may be able to create missing hooks at an already configured hooks path or change a writable fsmonitor hook. Read the warning on the approval card; approval does not neutralize those risks.

4. Keep Always-allow rules narrow

Always allow is offered only for commands that can save a supported narrow prefix, with a separate confirmation. It is not permission for every command from the same program:

• A git push rule does not authorize git commit.
• Git rules apply to the protected repository and reviewed options. They reject local-path remotes and options that can widen the command.
• Shell-form commands never match a saved rule.
• A matching Workspace command runs outside the sandbox without another approval card.

A push grant can still permit force-pushing or deleting remote branches. Save one only if you accept that scope and trust the repository’s hooks. Saved rules grant unsandboxed access; they do not restrict commands already allowed inside the sandbox.

Inspect the project’s rules from a terminal in that project:

TERMINAL

fungi permissions list

Copy the exact JSON prefix of a rule you intend to remove:

TERMINAL

fungi permissions remove '<json-prefix>'

You can also remove a rule in /permissions. The terminal asks for confirmation and defaults to keeping it. Removing a rule withdraws future automatic access; it does not undo commands that already ran.

What this sandbox does not promise

Both sandboxed modes hide Fungi’s credentials and service record, but not every file your OS user can read. Files such as ~/.ssh and ~/.aws remain readable. Do not treat Read-only as a secret-free environment.

Web, MCP and delegation tools are outside this command sandbox. Review their own permissions separately. Installed extension code also runs as you; an Agent’s sandbox is not isolation for trusted code installed in the Local service.

A macOS command needing network access can fail even in Workspace. A command needing to edit the project fails in Read-only. Those refusals reflect the selected permissions, not a reason to silently retry with broader access.

Continue with Use the terminal for Sessions and recovery, or Attach a local folder for the separate remote Computer attachment.