How to run an agent in an sbx sandbox

This guide shows how to declare an agent that runs inside a Docker sandbox (sbx), so that Sidekicks talks with it, shows its files and opens a terminal in it. It assumes sbx is installed and that you have a running sandbox containing the agent's program.

What Sidekicks needs

Setting	Role
`command` and `args`	how the agent is started: `sbx exec -i <sandbox> <program> <arguments>`. Sidekicks talks with it over stdin and stdout (ACP): `-i`, never `-t`.
`workspace`	the agent's folder on this computer. The command is started there, and the agent receives this same path as the working folder of its sessions. sbx mounts the host folders it shares at the same path, so it is also the folder seen inside the sandbox.
`runtime`	where its files and terminal are: `{type: sbx, sandbox: <sandbox>}`.

Steps

Make sure the sandbox runs and shares the agent's folder — it must list the folder's content at the same path:
```
sbx exec milo-sbx sh -c 'command -v mm; ls /Users/me/agents/milo/workspace'
```
If the folder is missing, share it when creating the sandbox (in its sbx configuration), then recreate it.

In Settings, add the agent and save:

agents:
  - name: milo
    title: Milo (sbx)
    icon: "🦊"
    command: sbx
    args: [exec, -i, milo-sbx, mm, -acp]
    workspace: /Users/me/agents/milo/workspace
    runtime:
      type: sbx
      sandbox: milo-sbx

Start the agent from the Agents panel (▶), or write to it: it answers from the sandbox. 📂 shows sandbox milo-sbx · /Users/me/agents/milo/workspace, its files and a terminal (sbx exec -it). Each file action takes a second or two: every one goes through sbx exec.

Variants

Sidekicks opened from the Finder: it may not find sbx in its short PATH. Write its full path (command: /usr/local/bin/sbx, see which sbx) or add env: {PATH: "…"} to the agent.
The model server runs on this computer: from inside the sandbox, reach it through host.docker.internal, as from a container.
Another program than mm (docker-agent, for instance): only args change, e.g. [exec, -i, my-sandbox, docker-agent, serve, acp, /path/to/agent.yaml].
Check without Sidekicks: sbx exec -it <sandbox> bash opens the same kind of shell as the Terminal tab.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


# How to run an agent in an sbx sandbox

This guide shows how to declare an agent that runs inside a Docker sandbox (`sbx`), so that Sidekicks talks with it, shows its files and opens a terminal in it. It assumes `sbx` is installed and that you have a running sandbox containing the agent's program.

## What Sidekicks needs

| Setting | Role |
| --- | --- |
| `command` and `args` | how the agent is started: `sbx exec -i <sandbox> <program> <arguments>`. Sidekicks talks with it over stdin and stdout (ACP): `-i`, never `-t`. |
| `workspace` | the agent's folder **on this computer**. The command is started there, and the agent receives this same path as the working folder of its sessions. sbx mounts the host folders it shares **at the same path**, so it is also the folder seen inside the sandbox. |
| `runtime` | where its files and terminal are: `{type: sbx, sandbox: <sandbox>}`. |

## Steps

1. Make sure the sandbox runs and shares the agent's folder — it must list the folder's content at the same path:

   ```bash
   sbx exec milo-sbx sh -c 'command -v mm; ls /Users/me/agents/milo/workspace'
   ```

   If the folder is missing, share it when creating the sandbox (in its sbx configuration), then recreate it.

2. In **Settings**, add the agent and save:

   ```yaml
   agents:
     - name: milo
       title: Milo (sbx)
       icon: "🦊"
       command: sbx
       args: [exec, -i, milo-sbx, mm, -acp]
       workspace: /Users/me/agents/milo/workspace
       runtime:
         type: sbx
         sandbox: milo-sbx
   ```

3. Start the agent from the **Agents** panel (▶), or write to it: it answers from the sandbox. **📂** shows `sandbox milo-sbx · /Users/me/agents/milo/workspace`, its files and a terminal (`sbx exec -it`). Each file action takes a second or two: every one goes through `sbx exec`.

## Variants

- **Sidekicks opened from the Finder**: it may not find `sbx` in its short `PATH`. Write its full path (`command: /usr/local/bin/sbx`, see `which sbx`) or add `env: {PATH: "…"}` to the agent.
- **The model server runs on this computer**: from inside the sandbox, reach it through `host.docker.internal`, as from a container.
- **Another program than mm** (docker-agent, for instance): only `args` change, e.g. `[exec, -i, my-sandbox, docker-agent, serve, acp, /path/to/agent.yaml]`.
- **Check without Sidekicks**: `sbx exec -it <sandbox> bash` opens the same kind of shell as the Terminal tab.

## See also

- [How to work with an agent's files and terminal](work-with-an-agents-files.md)
- [How to run an agent in a Docker container](run-an-agent-in-docker.md)
- [Reference: the configuration file](../reference/configuration.md) · [workspaces](../reference/agents-and-events.md#workspaces-milestone-m4)