c94e9e57
fix(docs): the published pages speak to operators, not to the tree
a73x 2026-08-10 13:48
Commit message
docs/mcp.md
| Old | New | ||
|---|---|---|---|
| @@ -3,7 +3,7 @@ | |||
| 3 | eitri gives Claude explicit tools for creating and controlling VMs on a fleet, | 3 | eitri gives Claude explicit tools for creating and controlling VMs on a fleet, |
| 4 | over two transports: | 4 | over two transports: |
| 5 | 5 | ||
| 6 | - **Local stdio** — `eitri-mcp` (`cmd/eitri-mcp`), a binary you run yourself. It | 6 | - **Local stdio** — `eitri-mcp`, a binary you run yourself. It |
| 7 | is an API client of the control plane plus SSH; it embeds no control-plane or | 7 | is an API client of the control plane plus SSH; it embeds no control-plane or |
| 8 | agent code, and it holds its own SSH user CA. | 8 | agent code, and it holds its own SSH user CA. |
| 9 | - **Remote HTTP** — `https://api.eitri.sh/mcp`, served by the control plane | 9 | - **Remote HTTP** — `https://api.eitri.sh/mcp`, served by the control plane |
| @@ -38,26 +38,21 @@ prompts gate every call regardless. | |||
| 38 | 38 | ||
| 39 | ## Setup: local stdio | 39 | ## Setup: local stdio |
| 40 | 40 | ||
| 41 | 1. Build the binary: | 41 | 1. Build the `eitri-mcp` binary from the eitri source tree with `make build`; |
| 42 | 42 | it lands in `bin/`. | |
| 43 | ``` | ||
| 44 | make build | ||
| 45 | ``` | ||
| 46 | |||
| 47 | (or `go build ./cmd/eitri-mcp`)—this produces `bin/eitri-mcp`. | ||
| 48 | 43 | ||
| 49 | 2. Create `~/.config/eitri-mcp/config.json`: | 44 | 2. Create `~/.config/eitri-mcp/config.json`: |
| 50 | 45 | ||
| 51 | ```json | 46 | ```json |
| 52 | { | 47 | { |
| 53 | "server_url": "http://127.0.0.1:8080", | 48 | "server_url": "http://127.0.0.1:8080", |
| 54 | "token_file": "~/eitri-deploy/eitri-mcp-token", | 49 | "token_file": "~/.config/eitri-mcp/token", |
| 55 | "gate": "127.0.0.1:2223", | 50 | "gate": "127.0.0.1:2223", |
| 56 | "vm_user": "ubuntu" | 51 | "vm_user": "ubuntu" |
| 57 | } | 52 | } |
| 58 | ``` | 53 | ``` |
| 59 | 54 | ||
| 60 | Fields (see `internal/mcpserver/config.go`): | 55 | Fields: |
| 61 | - `server_url`—required, the eitri API base URL. | 56 | - `server_url`—required, the eitri API base URL. |
| 62 | - `token_file`—required, path to a file holding a personal access token | 57 | - `token_file`—required, path to a file holding a personal access token |
| 63 | (mint one in the console Settings page; read at startup, held in memory, | 58 | (mint one in the console Settings page; read at startup, held in memory, |
| @@ -193,13 +188,3 @@ result or error. | |||
| 193 | > just-created VM some other way (e.g. its IP from `vm_list`/`vm_info` | 188 | > just-created VM some other way (e.g. its IP from `vm_list`/`vm_info` |
| 194 | > immediately after creation, or `wait: false`), it may still be mid-boot and | 189 | > immediately after creation, or `wait: false`), it may still be mid-boot and |
| 195 | > refuse connections for a short window. | 190 | > refuse connections for a short window. |
| 196 | |||
| 197 | ## Testing this yourself | ||
| 198 | |||
| 199 | Unit tests (`internal/mcpserver/*_test.go`, `internal/server/mcphttp/*_test.go`) | ||
| 200 | cover the tools and the HTTP transport against fake API and SSH seams. The | ||
| 201 | deploy boot-gate (`make deploy`) drives a whole VM life through the remote | ||
| 202 | endpoint with a bearer PAT: register a CA, `delegate_begin`, sign, refuse a | ||
| 203 | certificate from an unregistered CA, `delegate_complete`, `vm_create`, | ||
| 204 | `vm_exec`, `vm_expose`, dial the published port, publish a UDP port and echo a | ||
| 205 | datagram through it, `vm_destroy`. | ||
docs/quickstart.md
| Old | New | ||
|---|---|---|---|
| @@ -153,7 +153,7 @@ service listens on inside the guest—8080, say. Pick `tcp` or `udp`. Leave the | |||
| 153 | host port blank and eitri allocates one from 30000–32767, the range it reserves | 153 | host port blank and eitri allocates one from 30000–32767, the range it reserves |
| 154 | on every host. The row then reads: | 154 | on every host. The row then reads: |
| 155 | 155 | ||
| 156 | guest :8080/tcp → 192.168.0.190:30080 ● active | 156 | guest :8080/tcp → 192.168.1.40:30080 ● active |
| 157 | 157 | ||
| 158 | That address is the host's. Anything that can reach the host on that port | 158 | That address is the host's. Anything that can reach the host on that port |
| 159 | reaches the service—there is no authentication in front of a published port, so | 159 | reaches the service—there is no authentication in front of a published port, so |