The command sandbox

Bubbles with the shell tool can run commands in your project: installing packages, running builds and tests. Three layers decide what actually runs.

1. What a bubble may do at all

Each role holds a fixed set of tools. A Coder may write files and run commands; a Reviewer may run commands but not write files; a Researcher can do neither. You can narrow a bubble’s tools in its inspector. A bubble writes only inside its loop’s folder, whatever command it tries.

2. The command guard

Every command is read before it runs, and gets one of three answers.

Refused, always:

• running a shell directly (bash, sh, cmd, powershell, wsl), and anything that changes the shell itself;
• remote access (ssh, scp, rsync and the like), killing processes, changing permissions;
• destructive git (reset --hard, clean -f, force pushes, interactive commands) and publishing packages;
• any path outside the project, and any file that looks like a secret (.env, keys, certificates);
• a web address that is not a package registry, GitHub, Docker Hub or your own machine;
• anything that never exits, such as a dev server or a watch mode. Those belong in a terminal.

Asked, unless you have turned on Full Auto:

• git commits, pushes, merges, rebases, checkouts and similar;
• deleting files inside the loop’s folder;
• running inline code (node -e, python -c and the like).

Allowed: everything else, such as npm install or npm test.

Commands run without any environment variable whose name contains KEY, SECRET, TOKEN, PASSWORD, CREDENTIAL or PRIVATE. A command gets two minutes, or ten for package managers, compilers and test runners. When time runs out, the whole process tree is stopped.

Asking and Full Auto

When a command needs your say, the app asks. You can allow it once, or always for that kind of command until the app restarts. If no window is open to ask, the command is refused.

Full Auto turns every “ask” into “allow” for one board. It changes nothing else: refused commands, tool grants and folders still apply. It stays on until you turn it off.

3. The sandbox

The guard reads a command and refuses what it can see. A build script or a package’s install step can still write files no argument names. Sandbox agent commands (Settings, off by default) makes the operating system enforce the folders as well:

• the project is read-only, the loop’s own folder is writable, other loops’ folders inside it are read-only, and the app’s own folder is read-only;
• there is no network access from inside the sandbox.

System	How
Linux	bubblewrap (bwrap)
macOS	sandbox-exec
Windows	WSL with bubblewrap (the default), or Docker

With the sandbox on, a command that cannot be sandboxed is refused, never run without it. If a backend is not ready, Settings shows the one step to fix it, with the exact command to copy, for example installing bubblewrap inside WSL.

Perfica never installs a sandbox for you. The Docker image is downloaded only after you confirm a dialog that states its size.

Windows, project-root loops

On Windows the project is reached through WSL’s file sharing, where names are not case-sensitive. For a loop whose folder is the whole project, a command that spells the app’s folder in a different case can still write to it. Loops that own a sub-folder are not affected.

The terminal

The terminal dock at the bottom of the app is your own shell (Bash, PowerShell or CMD), not the agents’. The guard does not apply to it. Run in Terminal puts a command from a chat reply or a log entry on the terminal’s input line; it never presses Enter for you.