How to run mini-me in a 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
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

# How to run mini-me in a container

`mm dockerinit` writes a `Dockerfile` and a `compose.yaml` in the current directory. The image holds the latest released `mm` and the tools of its `bash` tool; compose mounts your project and runs the agent as you, not as root.

For Docker's microVM sandboxes rather than a plain container, see [how to run mini-me in a Docker Sandbox](run-in-a-docker-sandbox.md).

## Before you start

- Docker with Compose.
- An agent file in the project. If you have none, run `mm init` first (see [create an agent](create-an-agent.md)).
- A model server on your machine that the container can reach: see [Reach the model](#reach-the-model).

## Write the files

In your project's directory:

```bash
mm dockerinit
```

The service is named after `acp.name` in `agent.yaml`, or `mm` if there is none. To choose, use `mm dockerinit --name bob`. The rest of this guide calls it `bob`.

If a file already exists, mm asks `Overwrite Dockerfile?`, and `no` is the default. With `--yes`, or when the input ends, nothing at all is written.

## Run the agent

Either keep a container running, which also serves an editor:

```bash
docker compose up -d --wait
docker compose exec bob mm tui agent.yaml
```

Or run one session, in a container that goes away with it:

```bash
docker compose run --rm bob mm tui agent.yaml
```

Both open the [single-window mode](../reference/cli.md) (`mm tui`) and can be used at the same time. The first run builds the image.

## Connect an editor (ACP)

Start the container with `docker compose up -d --wait`, then give your editor this command, with the project's absolute path:

```bash
docker exec -i bob-box mm --acp --config /path/to/project/agent.yaml
```

The project is mounted at the same path as on your machine, so the paths the editor sends mean the same thing inside the container.

## Reach the model

From the container, `localhost` is the container. `dmr`, `llmman` and `ollama` fall back on `host.docker.internal` by themselves when their default address does not answer, as long as the agent file sets no `baseUrl`. The compose file makes that name known on Linux too.

- **`llamacpp`** has no such fallback: set `baseUrl: http://host.docker.internal:8080/v1`.
- **An agent file with a `baseUrl` on `localhost` or `127.0.0.1`:** replace the host with `host.docker.internal`, or add a `fallback`.
- **A server on Linux that only listens on `127.0.0.1`:** make it listen on an address the container can reach. `host.docker.internal` is then the host's gateway, not its loopback.

## Update to the latest release

```bash
docker compose build
docker compose up -d --wait
```

Docker reads the release's `SHA256SUMS` at each build: when it has changed, the steps that install `mm` run again.

## Build for both architectures

`docker compose` builds for your machine's architecture. To publish an image for `linux/amd64` and `linux/arm64`:

```bash
docker buildx build --platform linux/amd64,linux/arm64 -t <registry>/mm-bob:latest --push .
```

Building for the other architecture needs emulation (QEMU, included in Docker Desktop). Without it, the build stops with `exec format error`.

## Use the files on another machine

`compose.yaml` records the uid and gid of the machine that ran `mm dockerinit`, so that the files the agent creates belong to you. On a machine where yours differ, set them:

```bash
export MM_UID=$(id -u) MM_GID=$(id -g)
```

## What the container protects

The agent does not run as root, but it can still change and delete everything in the mounted project, and it has network access. Keep the project under version control, and use `yolo: false` if you want to approve each command: see [confirm tool calls](confirm-tool-calls.md).

All the flags are in the [CLI reference](../reference/cli.md#mm-dockerinit--the-container-files).