How to run an agent in a Docker container

 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

# How to run an agent in a Docker container

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

## What Sidekicks needs

Three settings work together:

| Setting | Role |
| --- | --- |
| `command` and `args` | how the agent is started: `docker exec -i <container> <program> <arguments>`. Sidekicks talks with it over stdin and stdout (ACP), so `-i` is required and `-t` must not be used. |
| `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 — so it must also exist **at the same path inside the container**. |
| `runtime` | where its files and terminal are: `{type: container, container: <container>}`. |

## Steps

1. Start the container with the agent's folder mounted at the same path, and an init process (it cleans up the programs the terminal ends):

   ```bash
   AGENT_DIR=/Users/me/agents/scout        # the agent's folder on this computer
   docker run -d --init --name scout-box \
     -v "$AGENT_DIR:$AGENT_DIR" -w "$AGENT_DIR" \
     my-agent-image sleep infinity
   ```

2. Check that the program runs and sees the folder:

   ```bash
   docker exec scout-box sh -c 'command -v mm; pwd; ls'
   ```

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

   ```yaml
   agents:
     - name: scout
       title: Scout (Docker)
       icon: "🐳"
       command: docker
       args: [exec, -i, scout-box, mm, -acp]
       workspace: /Users/me/agents/scout
       runtime:
         type: container
         container: scout-box
   ```

4. Start the agent from the **Agents** panel (▶), or write to it: it answers from the container. **📂** shows `container scout-box · /Users/me/agents/scout`, its files and a terminal.

## Restart or recreate the container

- **Stopped** (after a reboot, `docker stop`): nothing to do. Sidekicks starts it (`docker start`) before the agent; the **Log** tab shows `sandbox: container … stopped: starting it`.
- **Gone** (`docker rm`, a cleanup): give Sidekicks the command that creates it. In the assistant, choose **In a Docker container**, then drop the `compose.yaml` on **Recreate the container when it is gone** (or click **Choose a Compose file…**) and pick the service: the container name and the `docker compose` commands are filled in. Without Compose, type the `docker run -d --name …` command. In **Settings** it is `runtime.lifecycle`: see [the reference](../reference/configuration.md#runtimelifecycle-container-and-sbx).
- **■ Stop the container** and **🗑 Remove the container** then appear in the agent's header.

## Variants

- **Sidekicks opened from the Finder**: such an application gets a short `PATH` and may not find `docker`. Write its full path (`command: /usr/local/bin/docker`, see `which docker`), or add `env: {PATH: "…"}` to the agent. The files and the terminal find Docker by themselves.
- **The model server runs on this computer** (llmman, Ollama…): inside the container, `localhost` is the container itself; use `host.docker.internal` in the agent's own configuration.
- **The folder is mounted elsewhere in the container**: set `runtime.workspacePath` to that path for the files and the terminal. The agent's sessions still receive `workspace` as their working folder, so prefer the same path.
- **An existing container**: any running container works, as long as it has the program and the folder; `docker ps` gives its name.

## See also

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