> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kanaeru.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxing and capacity

> How the Agent Manager keeps agents inside their workspace, and how to tune how many run at once.

Coding agents run commands on your machine. The Agent Manager confines each one to the files it needs and keeps sessions apart from each other.

## The standard sandbox

By default, every runtime runs under the **standard** sandbox policy. It:

* **Limits writes** to the workspaces assigned to the session, a private state and temp directory per session, and the credential stores that session's runtime declares. On macOS, the rest of your home directory, other users' files, and shared locations are also hidden from reads. On Linux the rest of the filesystem stays readable, but not writable.
* **Allows** read-only access to the tool directories agents need. There's no blanket access to the operating system's credential store: the macOS keychain is opened to a session only when the machine's shared login lives there.
* **Doesn't restrict the network.** Agents can reach the internet to install packages and call APIs, and they can start local servers and connect to local ports.

If the machine can't enforce the policy, the runtime doesn't start. It never falls back to running unsandboxed.

## Where the sandbox runs

| Machine | Enforcement |
| - | - |
| macOS | Seatbelt, the macOS sandbox |
| Linux and WSL, installed directly | bubblewrap (`/usr/bin/bwrap`). The installer refuses to continue without it. If the host is already isolated, such as a dedicated VM, you can set `KANAERU_RUNTIME_EXTERNALLY_ISOLATED=1` to run without it |
| Docker Engine install and cloud machines | bubblewrap inside the container, on top of the container's or cloud provider's isolation |
| Windows | No built-in sandbox. Agents only start if you set `KANAERU_RUNTIME_EXTERNALLY_ISOLATED=1` on an isolated host, or `KANAERU_SANDBOX_POLICY=permissive` |

On macOS too, `KANAERU_RUNTIME_EXTERNALLY_ISOLATED=1` turns Seatbelt off, so only set it on a host that's isolated some other way.

```mermaid theme={null}
%%{init: {"theme":"base","themeVariables":{"fontFamily":"Inter, ui-sans-serif, system-ui, sans-serif","fontSize":"16px","primaryColor":"#FFF1E0","primaryBorderColor":"#A94604","primaryTextColor":"#3B1A02","secondaryColor":"#FFE4C2","tertiaryColor":"#FFF8F0","lineColor":"#A94604","clusterBkg":"#FFF8F0","clusterBorder":"#E8B98A","edgeLabelBackground":"#FFFFFF","git0":"#A94604","git1":"#FF9F0A","git2":"#D97706","git3":"#B45309","gitBranchLabel0":"#FFFFFF","gitBranchLabel1":"#3B1A02","gitBranchLabel2":"#FFFFFF","commitLabelColor":"#3B1A02","commitLabelBackground":"#FFF1E0"}}}%%
flowchart TD
  A[Runtime starting] --> P{Policy is permissive?}
  P -- yes --> U[Runs without a filesystem sandbox]
  P -- no --> C{Docker install or cloud machine?}
  C -- yes --> W[bubblewrap sandbox]
  C -- no --> D{Host declared isolated?}
  D -- yes --> E[Relies on the host's isolation]
  D -- no --> L{Linux or WSL?}
  L -- yes --> W
  L -- no --> B{macOS?}
  B -- yes --> S[Seatbelt sandbox]
  B -- no --> X[Runtime doesn't start]
```

## Settings

Set these in the Agent Manager's environment on the machine.

| Variable | Values | Effect |
| - | - | - |
| `KANAERU_SANDBOX_POLICY` | `standard` (default), `permissive` | `permissive` turns the filesystem sandbox off. Only use it on a machine dedicated to Kanaeru. Applies to every runtime |
| `KANAERU_RUNTIME_EXTERNALLY_ISOLATED` | `1` | Declares that the host is already isolated, such as a dedicated VM, so runtimes start without the built-in sandbox. Has no effect on cloud machines or the Docker install |
| `KANAERU_SANDBOX_DOCKER` | `allow` (default), `deny` | Whether sessions may use the host's Docker daemon. Applies to every runtime. `deny` is enforced by the macOS sandbox only |
| `KANAERU_CLAUDE_PERMISSION_MODE` | `confirm` | Claude Code only. Ask a person before Claude Code runs a tool, instead of letting it run tools on its own. Other runtimes don't have an equivalent setting |

<Warning>
  Access to the host Docker daemon is effectively access to the host. Set `KANAERU_SANDBOX_DOCKER=deny` on any machine where that matters.
</Warning>

### Running your app with Docker denied

`deny` only blocks the Docker CLI and the Docker daemon. Agents can still run, test, and serve your app as ordinary processes inside the sandbox, such as `npm run dev` or a Python server, and connect to it on a local port. Keep anything the app writes, such as a local database's data directory, inside the workspace. If your app can only run under Docker Compose, leave Docker set to `allow` on that machine, ideally one dedicated to Kanaeru.

## Capacity

The Agent Manager sizes how many agents run at once from the machine's memory and CPU. Roughly:

* 2 to 4 on small machines
* 8 on 4 cores with 8 GB
* 12 on 8 cores with 16 GB
* 15 at most

It also stops admitting new work when the CPU or memory is under pressure. To change the limit:

| Variable | Effect |
| - | - |
| `KANAERU_CAPACITY_PRESET` | `conservative` (4), `balanced` (8), or `performance` (15) |
| `KANAERU_MAX_CONCURRENT` | An exact limit from 1 to 100. Invalid values fall back to the automatic size |
| `KANAERU_MAX_CPU_LOAD_RATIO` | Stop admitting work above this CPU load ratio (default `0.95`) |
| `KANAERU_MAX_RUNTIME_RSS_GIB` | Memory ceiling for running agents (default 75% of RAM) |

Agents that are idle between turns don't count against the limit. Work that can't start is retried for up to a minute. If no capacity frees up by then, the session doesn't start, and Kana tells you every machine was busy so you can send the message again.


## Related topics

- [Connect a machine](/machines/connect-a-machine.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.