# The sandbox

Source: https://cohalen.com/docs/sandbox



<Callout type="warn">
  A git worktree keeps parallel work apart. It isn't a security boundary.
</Callout>

The sandbox profile is what the coding agent, the project scripts, and the terminal
all run under, set per workspace. It has four layers you can switch on and off
independently:

1. **Filesystem confinement**: writes go no further than the workspace's worktree.
2. **The egress allowlist**: network access is denied unless you allow it.
3. **Secret hygiene**: a stripped-down environment and redaction, so secrets on
   your machine stay out of the agent's reach and out of its output.
4. **Resource limits and the spend cap**.

<Mermaid
  chart="`flowchart TB
accTitle: The four sandbox layers, nested
accDescr {
  The workspace worktree, where the agent, the scripts, and the terminal run,
  sits inside filesystem confinement. That sits inside the egress allowlist,
  which sits inside secret hygiene, which sits inside resource limits and the
  spend cap.
}
subgraph L4 [&#x22;Resource limits + spend cap&#x22;]
  subgraph L3 [&#x22;Secret hygiene&#x22;]
    subgraph L2 [&#x22;Egress allowlist&#x22;]
      subgraph L1 [&#x22;Filesystem confinement&#x22;]
        WT[&#x22;Workspace worktree<br/>agent · scripts · terminal&#x22;]
      end
    end
  end
end`"
/>

Two presets cover the common cases, and any mix in between is allowed.

<Tabs items="[&#x22;Sandboxed&#x22;, &#x22;Trusted&#x22;]">
  <Tab value="Sandboxed">
    All four layers on. This is the default, and it's what a workspace you leave
    running unattended should be on.
  </Tab>

  <Tab value="Trusted">
    All four layers off: the full-access escape hatch, for a repository whose scripts
    need the machine.
  </Tab>
</Tabs>

A workspace starts on its repository's default profile. It can tighten a layer on
its own, but loosening one is something you do per workspace, on purpose.

## Who enforces it [#who-enforces-it]

The profile is one policy; the muscle behind it is whoever does it best. An
agent that ships its own OS-enforced sandbox gets Cohalen's policy written into
it, rather than a second cage built around the first. Everything that sandbox
can't reach stays under Cohalen's own enforcement: the terminal, the project
scripts, agents that bring no sandbox of their own, and Windows.

The profile always tells you which enforcer is in force. A profile that claims a
layer nobody is enforcing would be the defect.

In a [box](/docs/cloud), the box itself is the boundary: one workspace per
machine, so there's no neighboring work to confine it from. The egress allowlist
still applies, expressed through the vendor's own network policy where it has
one.

The profile lives in config Cohalen owns, and Cohalen never commits it to a
repository. So an agent can't edit its own cage through the files it works on.

## The egress allowlist [#the-egress-allowlist]

With the network layer on, a workspace reaches only the hosts on its allowlist.
Everything else gets turned down.

Enforcement never leaves your custody, and it works with whatever proxy you
already use instead of replacing it.

The default list covers the common package registries, GitHub, and certificate
authorities. The active agent's own API endpoints are always allowed, so the agent
keeps working. You widen the list in **Settings**, and a file committed to a repo
never can.

## The spend cap [#the-spend-cap]

The fourth layer is the budget: when a turn's spend crosses the workspace's cap,
the turn stops. The [spend page](/docs/spend) owns the meter, what it covers,
and where the rest of the money goes.

No profile turns the cap off quietly. Runaway cost comes from accidents, not
only from code you don't trust. That's what lets you leave agents working
unattended: the worst case has a number on it.