Playing Lego with kits: Docker Agent + Rust

 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

# Playing Lego with kits: Docker Agent + Rust

A **kit** is a reusable brick to compose a sandbox. Here, we assemble two kits in `sbxenv.yaml`:

| Kit | Role |
|-----|------|
| `kits/docker-agent-mistral` | the **workload** (the base): Docker Agent, started directly on `agent.yaml`, with access to the Mistral API |
| `kits/rust-toolchain` | a **mixin**: the Rust toolchain (`cargo`, `rustc`, `rustfmt`, `clippy`, `rust-analyzer`) |

A set of v3 kits contains **exactly one workload** and as many mixins as you want. A single v3 mixin combined with the built-in `docker-agent` agent (which is a v2 kit) is refused: `no workload kit in the set`.

## The `sbxenv.yaml` file

```yaml
schemaVersion: "1"
name: docker-rust-agent-mistral
agent: docker-agent-mistral
workspace: .
env:
  DOCKER_AGENT_AUTO_UPDATE: "0"
  MISTRAL_API_KEY: sbx-mistral-key

kits:
  - ./kits/docker-agent-mistral
  - ./kits/rust-toolchain
```

- `agent`: must carry the name of the workload kit (the file name `docker-agent-mistral.yaml`).
- `kits`: the workload, then the mixins. Relative paths are resolved against this file.
- `env`: `MISTRAL_API_KEY` only contains the **placeholder value**, never the real key.

## The workload kit: `docker-agent-mistral`

- `docker-agent-mistral.dockerfile` starts from the `docker/sandbox-templates:docker-agent-docker` image and defines the launch command (`ENTRYPOINT`/`CMD`): `docker-agent run agent.yaml`.
- `docker-agent-mistral.yaml` declares `kind: workload` and allows outbound traffic to `api.mistral.ai`.

## The mixin kit: `rust-toolchain`

- `rust-toolchain.dockerfile` builds a layer with the Rust toolchain and the linker (`gcc`); it is only added on top of the image.
- `rust-toolchain.yaml` declares `kind: mixin`, the `rust_version` argument (default `1.99.0`) and allows outbound traffic to crates.io.

To change the Rust version without modifying the files:

```bash
sbx env create --kit-arg rust_version=stable
```

## Custom secret

`sbxenv.yaml` cannot declare a custom secret: we create it beforehand. With `--sandbox`, it is removed along with the sandbox by `sbx env rm`:

```bash
export MISTRAL_API_KEY="your-api-key"
sbx secret set-custom --sandbox docker-rust-agent-mistral \
--host api.mistral.ai --env MISTRAL_API_KEY \
--placeholder sbx-mistral-key --value "$MISTRAL_API_KEY"
```

🖐️🖐️ **on Windows:**
```bash
$env:MISTRAL_API_KEY="your-api-key"

sbx secret set-custom --sandbox docker-rust-agent-mistral --host api.mistral.ai --env MISTRAL_API_KEY --placeholder sbx-mistral-key --value "$env:MISTRAL_API_KEY"
``` 

Without `--sandbox`, the secret is global and works too.

## Start the sandbox

```bash
sbx env create
sbx env exec -it -- docker-agent run agent.yaml
```
> 🖐️ **you need Docker to build a kit**

`sbx env` shows the plan (what is going to be created) and asks for approval; `--force` accepts it without asking. The first creation builds the two kits, which takes a little time.

Other useful commands:

```bash
sbx env plan   # preview the changes
sbx env rm     # remove the sandbox and its secrets
```

## And try

```raw
What is the version of cargo?
```


```raw
Create a new Rust project with cargo that prints a greeting, then build and run it
```

The agent can now use `cargo build`, `cargo test` or `cargo clippy` in the sandbox.