Step-by-step guide

Contain command execution

Put shell work inside a filesystem and network boundary you can inspect before the run begins.

You will build: A Linux command boundary that fails closed when unavailable.
Time: 5 minutes
Before you start: Linux with Bubblewrap available.

What this changes

The guard decides whether a command may run; the sandbox decides where an approved command runs. Configure both so the agent has useful room to work without silently inheriting the whole host.

01
A visible boundary
The effective filesystem, network and host-availability posture is explicit for the run.
02
Fail-closed execution
A required boundary stops command work on an incompatible host instead of quietly running it directly.
03
Deliberate host access
Beyond a read-only system root and the toolchains Clarvis discovers for you, only the environment values and extra paths you name cross into the command sandbox.

Minimum setup

Start with one working configuration.

Choose the boundary independently from command review. The protected shape below reviews commands before they run and executes approved ones inside a writable workspace with host networking. With no allowed_commands the guard asks about every command, not only risky ones, so add that list once the routine commands are known.

~/.clarvis/settings.json sandbox · JSON

{
  "guard": {
    "type": "shell",
    "mode": "on"
  },
  "sandbox": {
    "type": "bubblewrap",
    "enabled": true,
    "availability": "required",
    "filesystem": "workspace-write",
    "network": "host",
    "toolchains": {
      "mode": "auto"
    }
  }
}

Why this is the minimum

The Bubblewrap boundary applies to shell and monitor_start on Linux. Built-in file tools remain constrained by workspace confinement and the agent grants, not by this command sandbox.

Working patterns

Adapt it to work you actually do.

Open a pattern to see the complete files and the reason behind each choice.

Pattern 01 Remove network access from commands Configuration

You want the agent to inspect and test a checkout, but nothing launched through the shell should reach a package registry, API, or arbitrary host.

Remove network access from commands example

{
  "sandbox": {
    "type": "bubblewrap",
    "enabled": true,
    "availability": "required",
    "filesystem": "workspace-write",
    "network": "none",
    "toolchains": { "mode": "auto" }
  }
}

With network set to none, the command receives no host network namespace and no
DNS resolver mount. Package downloads and remote API calls will fail by design.

Pattern 02 Make command access read-only Configuration

You are delegating investigation rather than implementation. Shell commands may inspect the repository, but they should not be able to change it or reach the network.

Make command access read-only example

{
  "sandbox": {
    "type": "bubblewrap",
    "enabled": true,
    "availability": "required",
    "filesystem": "workspace-read-only",
    "network": "none",
    "toolchains": { "mode": "auto" }
  }
}

This setting contains shell and monitor_start. Also remove edit_workspace from the
agent profile: built-in file-editing tools are governed by grants and workspace
confinement, not by the Bubblewrap command boundary.

Verify the behavior

Check the boundary, not just the happy path.

Use a small disposable task first. Confirm what works and what is deliberately unavailable before relying on the configuration in a real workflow.

01
The effective sandbox reports Bubblewrap as available before the run begins.
02
A required sandbox refuses command execution instead of falling back to the host when containment is unavailable.
03
The filesystem and network posture shown for the run match the values you selected.

Next guide

Add a deterministic checkpoint

Inspect a lifecycle event and return an explicit pass, advice, context, or denial.

Continue All guides