Maple Harness home

Maple Harness 2.6.2 released! What's new in 2.6.2

Single userTeams & hubs

One person, one machine: the agent, the proxy and your own usage.

Several people, from one shared proxy up to a hub of hubs.

The shell sandbox #

On this page
  1. In plain words
  2. What it does
  3. What it breaks
  4. Turning it on
  5. Contain commands whenever nobody approves them
  6. When a command is blocked
  7. Recommended setup
  8. Platforms

The agent runs shell commands for you through its bash tool. Those commands run as you, with your files, your logins and your network. The sandbox contains them: when it is on, a command the model runs can change your project but not the rest of your computer, and cannot read the places where your credentials live.

It is off by default for an ordinary session and on (auto) by default while a session is shared for remote control. /sandbox shows its state at any time.

In plain words #

  • What it is. A fence around the commands the agent runs: they can change your project, but not the rest of your computer, and cannot see where your keys and logins live.
  • Why you want it. A mistaken or malicious command cannot read your SSH key or your cloud login.
  • What to do. /sandbox in a session shows whether it is on; /sandbox auto turns it on for the session. It is on by default while a session is shared with your phone. Some things (pushing over SSH) then fail; the table below says what to do.

What it does #

While the sandbox is on, every bash command runs with these limits:

What contained commands get
WritableYour project folder, a private temporary folder, and the usual build caches under your home folder (~/.cache, ~/go, ~/.npm, ~/.cargo, ~/.gradle, ~/.m2 and similar), so builds and installs into the project work. Everything else is read-only. Inside the project, .git/hooks and .git/config are read-only too, because they run code on the next git command
HiddenPlaces that hold logins and keys look empty: ~/.ssh, ~/.gnupg, ~/.aws, ~/.azure, ~/.kube, ~/.docker, ~/.config/gcloud, ~/.config/gh, browser profiles, other coding agents' folders, ~/.netrc, ~/.git-credentials, ~/.npmrc, ~/.pypirc, the Maple Harness settings folder, the Docker and Podman sockets, and your session's runtime folder (where ssh-agent and keyring sockets live)
EnvironmentVariables that look like secrets are removed: names containing TOKEN, SECRET, PASSWORD or API_KEY, names starting with AWS_, GH_, GITHUB_ and similar, and SSH_AUTH_SOCK. sandbox.env_allow keeps the ones you name
NetworkAllowed for a local session, off while the session is shared. /sandbox network allow or deny changes it for the session; sandbox.network in config.yaml makes it stick
The setup pageWhere the system supports it, contained commands cannot connect to the proxy's setup page, so a command cannot change your settings or read your keys through it. Everything else on the network stays reachable while the network is allowed. /sandbox says whether the page is blocked on your machine

What it breaks #

Anything that needs a hidden login, or writes outside the project, fails while the sandbox is on:

ToolWhy it failsWhat to do
git push, git pull over SSH, ssh, scp~/.ssh is hidden, so there is no key and no known hostsPush yourself, allow ~/.ssh for the session, or run that one command outside the sandbox
gh~/.config/gh is hidden and GH_TOKEN is removedSame
aws, gcloud, azTheir login folders are hidden and cloud variables are removedSame
kubectl, helm~/.kube is hiddenSame
docker, podmanThe daemon socket is hiddenSame
npm install -g, pip install --user, go install to a folder outside the cachesWrites outside the project are read-onlyInstall into the project, or allow the folder with --write
Signed commits~/.gnupg is hiddenCommit yourself, or allow ~/.gnupg
Anything that reads your home folder, when the home folder is under the temporary folder (a CI container with HOME=/tmp, say)Every command gets its own empty temporary folder, so a home inside it is not there (only the build caches are)Set HOME to a folder outside the temporary folder, such as the project's parent

Git over HTTPS with a token in ~/.git-credentials or ~/.netrc fails the same way.

Turning it on #

SettingWhat it does
/sandbox autoContain commands in this session. Without a backend (see Platforms) commands still run, uncontained, and the first result says so
/sandbox strictContain commands in this session, and refuse to run any command when there is no backend
/sandbox offNo containment in this session
harness.sandbox.mode: auto or strict in config.yamlThe same, for every session

/sandbox changes last for the session. An explicit sandbox.mode (including off) always wins over the defaults and over the option below.

Contain commands whenever nobody approves them #

In ask mode you see each command before it runs. In auto and yolo mode commands run without a person approving each one, and that is where containment matters most. This option turns the sandbox on exactly then:

harness:
  sandbox:
    when_unattended: on      # off by default

With it on, and sandbox.mode not set:

  • In auto or yolo mode, commands are contained (as with auto).
  • In ask mode, commands run as they do today.
  • Switching mode with shift+tab applies to the next command. /sandbox says why commands are contained ("contained because commands run without approval") and the status bar shows it.
  • A helper agent (subagent) follows the same rule, from its own mode: it is contained when its asks go through without anyone approving them, for example when the main session is in auto mode.
  • Commands started in the background follow the rule for the mode they were started in.

With it off, which is the default, nothing changes. An explicit sandbox.mode: off keeps the sandbox off even with it on, and an explicit auto or strict contains every command in every mode. It covers the bash tool; MCP servers are contained by sandbox.mode alone.

When a command is blocked #

When a contained command fails because of the sandbox, the result says so in plain words, for you and for the model. For example:

[sandbox] Blocked by the sandbox: ~/.ssh is hidden, so ssh and git over SSH can't authenticate.
A git push that failed inside the sandbox: the command's own error, then the note Blocked by the sandbox: ~/.ssh is hidden, so ssh and git over SSH can't authenticate, the ways to allow it, and the model's reply saying what it neededA git push that failed inside the sandbox: the command's own error, then the note Blocked by the sandbox: ~/.ssh is hidden, so ssh and git over SSH can't authenticate, the ways to allow it, and the model's reply saying what it needed
A git push over SSH blocked by the sandbox: the note says why, and the model stops and tells you what it needed.

It says "blocked" only when the failure names a place the sandbox hides or keeps read-only, or the network is off. When it cannot tell (a bare "Permission denied", or a login failure that names no file) it says "may have been blocked". An ordinary failure, such as a failing test, gets no note. The model is told not to work around it and to tell you what it needed.

You then have three choices:

  • Allow the path for this session: /sandbox allow ~/.ssh makes it readable (read-only). Add --write to make a folder writable. Every contained command can then read what you allowed, so allow the one folder a task needs. It refuses the root folder, your home folder, any folder that contains a hidden one (allowing it would un-hide that too), the Maple Harness settings folder and your session's runtime folder.
  • Allow it permanently: add --save, for example /sandbox allow ~/bin --write --save. That adds the path, made absolute, to sandbox.extra_readonly (or sandbox.extra_writable with --write) in your config.yaml. You can also edit those lists directly. For folders that hold logins or keys, the note only suggests the session form.
  • Run that one command outside the sandbox. Ask the model to; it retries the command marked to run outside the sandbox. You are asked to approve each run, even in auto or yolo mode, the question says the command runs outside the sandbox, and "always" is not offered for it. It is refused when nobody can approve (a session with no one at the keyboard, or a helper agent with no way to ask you), while the session is shared with other devices, and when sandbox.mode is strict. The next command is contained again.

/sandbox and /sandbox allow work only in the terminal the session runs in. A device driving the session remotely cannot loosen the sandbox.

  • Install the backend (below) and run /sandbox or maple-harness doctor to check it works.
  • If you use auto mode, turn on sandbox.when_unattended.
  • Set a password for the proxy's setup page (More > Protect this page, or maple-proxy setup-password set). The sandbox keeps contained commands away from the page; the password keeps other programs and browsers on this computer away from it. Together they cover both. See The proxy.
  • Allow only the paths a task needs, and prefer /sandbox allow for the session over --save.

Platforms #

SystemBackendStatus
Linuxbubblewrap (optional install, below)Verified. Blocking the setup page needs Linux 6.7 or later; on an older kernel commands can still reach it, and /sandbox says so
macOSThe built-in sandbox-exec, nothing to installBuilt, but not yet run on a Mac by us: treat it as unverified
WindowsNoneThere is no sandbox on Windows. auto runs commands uncontained and says so; strict refuses to run them

Install bubblewrap on Linux:

SystemCommand
Arch, Manjarosudo pacman -S bubblewrap
Debian, Ubuntusudo apt install bubblewrap
Fedora, RHELsudo dnf install bubblewrap
openSUSEsudo zypper install bubblewrap
Alpinesudo apk add bubblewrap

Every sandbox setting is listed in Harness settings, and the commands in Commands and keys.

Made with ❤️ by Kinn Coelho Juliao in Ottawa, eh — fuelled by double-doubles, bud. 🍁