How to run mini-me with the v3 sandbox kits

  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
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111

# How to run mini-me with the v3 sandbox kits

This guide shows how to run `mm` in a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/) with the kits written for the [kit specification v3](https://github.com/docker/sandbox-kit-spec), under [`docker-sbx-v3/`](../../../docker-sbx-v3/README.md). They do the same job as the v2 kits of [Run mini-me in a Docker Sandbox](run-in-a-docker-sandbox.md) — the window mode with `mm-tui`, an editor with `mm-acp` — and the v2 kits keep working beside them. It assumes Docker Desktop with the `sbx` command, and a model server (Docker Model Runner or llama-server) running on your machine.

> **Status.** The v3 kits build with the `docker/sandbox-kit:3` frontend and pass the specification's conformance check (`kit-tck validate`), but they have not yet been run with `sbx`, and they are not published yet. The kit specification itself is still marked experimental.

| Piece | What it is |
|---|---|
| `template/Dockerfile` | The **template** image, `k33g/mm-sandbox:<version>` — the same image as v2. |
| `kits/mm-tui/mm-tui.yaml` + `mm-tui.dockerfile` | The window-mode kit: a descriptor (declarations) and a Dockerfile (content: `FROM` the template, `ENTRYPOINT ["mm-tui"]`). |
| `kits/mm-acp/mm-acp.yaml` + `mm-acp.dockerfile` | The editor kit, same shape, `ENTRYPOINT ["mm-acp-info"]`. |
| `build.sh`, `sync-kits.sh` | Build the template, and point the kits at it. |
| `check-kits.sh` | Builds the kits locally and checks them, with no `sbx` and no push. |
| `push-kits.sh`, `publish.sh` | Publish the kits (and the template) to Docker Hub with `docker buildx`. |

## Before you start: two differences with v2

- **The template image must be on a registry.** A v3 kit is *built* on top of the template. When you run a kit from its directory, `sbx` builds it in its builder sandbox, and that sandbox's Docker engine pulls the template from the registry. An image that exists only in your local image store is not enough, and `--pull never` or `sbx template load` do not help. `k33g/mm-sandbox:0.2.1` is already on Docker Hub; for another version, push it first (step 1).
- **The workspace is `/home/agent/workspace`.** The template's base image declares that working directory, and a v3 agent workload (`sbx@1`) is mounted there. Give `config` a path relative to the workspace (`agent.dmr.yaml`, `demo/agent.dmr.yaml`); an absolute path of your Mac (`/Users/…`) does not exist inside the sandbox.

## Steps

### 1. Make the template available

For the version in `release.env` (`v0.2.1`), nothing to do: `k33g/mm-sandbox:0.2.1` is on Docker Hub. For a work-in-progress `mm`, build and push the template from the repository root:

```bash
PUSH=1 ./docker-sbx-v3/build.sh v0.2.2
```

The script builds `k33g/mm-sandbox:0.2.2` for linux/amd64 and linux/arm64, pushes it, then rewrites the kits' `image` and `tag` defaults so they name that image. `IMAGE_OWNER=<handle>` pushes under your own account instead.

### 2. Check the kits (optional)

```bash
./docker-sbx-v3/check-kits.sh
```

Each kit is built with `docker buildx build -f <kit>.yaml`, which runs the kit frontend: it refuses an unknown key or an argument that does not match its pattern. The result goes to `tmp/kits-v3/<kit>/`. With [`kit-tck`](https://github.com/docker/sandbox-kit-spec) on the `PATH` (`go build ./cmd/kit-tck` in a clone of the specification), the script also runs the conformance check and prints `✓ conforms`.

### 3. Window mode in the terminal (kit `mm-tui`)

From the project you want `mm` to work on:

```bash
cd /path/to/your/project
sbx run /path/to/mini-me/docker-sbx-v3/kits/mm-tui . -- agent.dmr.yaml
```

The first run builds the kit (a few seconds: one layer over the template), creates the sandbox, mounts the current directory and runs `mm -tui agent.dmr.yaml`. What follows `--` is `mm`'s own command line. Without it, `mm` reads the kit's `config` argument, then `./agent.yaml`, then its built-in defaults:

```bash
sbx run /path/to/mini-me/docker-sbx-v3/kits/mm-tui . --kit-arg config=agent.dmr.yaml
```

### 4. From an editor (kit `mm-acp`)

1. Create the sandbox once, from the project the editor will open:

   ```bash
   cd /path/to/your/project
   sbx create --name mm-acp /path/to/mini-me/docker-sbx-v3/kits/mm-acp . \
       --kit-arg config=agent.dmr.yaml
   ```

2. Register it in the editor. In Zed's `settings.json`:

   ```json
   {
     "agent_servers": {
       "mini-me (sandbox)": {
         "type": "custom",
         "command": "sbx",
         "args": ["exec", "-i", "mm-acp", "mm", "-acp"]
       }
     }
   }
   ```

3. Open the agent panel and pick **mini-me (sandbox)**. As with v2, the editor runs `sbx exec -i`, because an ACP client needs raw stdin and stdout and `sbx run` always allocates a terminal. `sbx run --name mm-acp` prints this wiring and opens a shell.

### 5. Once the kits are published

After `./docker-sbx-v3/publish.sh` (or `push-kits.sh`) has run for a version, the kits are ordinary images on Docker Hub, and no directory is needed:

```bash
sbx run k33g/sbx-kit-mm-tui:0.2.1 . -- agent.dmr.yaml
sbx create --name mm-acp k33g/sbx-kit-mm-acp:0.2.1 . --kit-arg config=agent.dmr.yaml
```

The repositories are `sbx-kit-<kit>`, not the v2 `k33g/mm-tui` / `k33g/mm-acp`, so that publishing a v3 kit never replaces a v2 one.

## Kit arguments

| `--kit-arg` | Default | When it applies | Effect |
|---|---|---|---|
| `config=<path>` | empty | at `sbx run` / `sbx create` | `mm`'s `AGENT_CONFIG`: relative to the workspace, or absolute inside the sandbox. Empty: `./agent.yaml`, then the built-in defaults. |
| `tag=<version>` | mm's version (`0.2.1`) | when the kit is built | Which template tag the kit is built on; also the kit's version. No `v`. |
| `image=<repository>` | `k33g/mm-sandbox` | when the kit is built | Which template repository the kit is built on. |

`tag` and `image` are build-phase arguments: they are fixed in a published kit, which always names the image it was built on. To use another `mm` version, take the kit of that version.

## The model server stays on the host

Unchanged from v2: Docker Model Runner and llama-server run on your machine and are reached through `host.docker.internal`. `agent.dmr.yaml` already falls back to it; for llama-server see [the v2 guide](run-in-a-docker-sandbox.md#the-model-server-stays-on-the-host). Both kits allow ports 12434 and 8080 on the host; for another port, `sbx policy allow network host.docker.internal:<port>`.

## See also

- What changed from the v2 kits, field by field: [`docker-sbx-v3/README.md`](../../../docker-sbx-v3/README.md).
- The v2 kits, the MCP gateway and the editor variants: [Run mini-me in a Docker Sandbox](run-in-a-docker-sandbox.md).
- The kit format: [specification v3](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md).