How to run an agent in an sbx sandbox

 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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

# 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`.

## Recreate the sandbox when it is gone

When the sandbox is removed (by you, by `sbx rm`, after a reset of sbx), the agent can no longer start. Give Sidekicks the commands that manage the sandbox and it creates it again before starting the agent:

1. With the assistant: choose **In an sbx sandbox**, then drop the sandbox's `sbxenv.yaml` on the **Recreate the sandbox when it is gone** area (or click **Choose an sbxenv.yaml…**). The sandbox name, the folder and the `sbx env` commands are filled in; change them if needed.
2. Or in **Settings**, add `lifecycle` to the runtime:

   ```yaml
       runtime:
         type: sbx
         sandbox: milo-sbx
         lifecycle:
           folder: /Users/me/agents/milo
           create: [sbx, env, create, --force]
           stop: [sbx, stop, milo-sbx]
           remove: [sbx, env, rm, --force]
   ```

3. Start the agent: if `milo-sbx` does not exist, the **Log** tab shows `sandbox: sandbox milo-sbx not found: creating it` and the output of `sbx env create`, then the agent starts. Creating a sandbox can take a minute (the kits are pulled).

The **■ Stop the sandbox** and **🗑 Remove the sandbox** buttons appear in the agent's header when `stop` and `remove` are set. All the keys: [`runtime.lifecycle`](../reference/configuration.md#runtimelifecycle-container-and-sbx).

## Variants

- **The sandbox name is not the `name:` of the sbxenv.yaml**: after `create`, Sidekicks still finds no sandbox and says so. Make `sandbox` and `name:` the same.
- **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)