docs: Added docs for the new docker image and sandbox that uses the image to run

2026-07-15 13:20:56 -06:00
parent 5f98eeb427
commit 8293cab119
2 changed files with 32 additions and 5 deletions
+26
@@ -48,6 +48,32 @@ To upgrade `coyote` using Homebrew:
brew upgrade coyote
```
## Docker
Coyote is available as a Docker image on Docker Hub (`darkalex17/coyote`) for Linux amd64 and arm64.
Useful for CI, ephemeral environments, or anywhere you prefer not to install it natively.
```bash
docker pull darkalex17/coyote
docker run --rm -it darkalex17/coyote
```
To persist your configuration across container runs, mount your existing config directory:
```bash
docker run --rm -it \
-v ~/.config/coyote:/home/agent/.config/coyote \
darkalex17/coyote
```
If you use the local vault provider and want your vault credentials available in the container, also mount the password file:
```bash
docker run --rm -it \
-v ~/.config/coyote:/home/agent/.config/coyote \
-v ~/.coyote_password:/home/agent/.coyote_password:ro \
darkalex17/coyote
```
## Scripts
### Linux/MacOS (`bash`)
You can use the following command to run a bash script that downloads and installs the latest version of `coyote` for your
+6 -5
@@ -28,9 +28,10 @@ coyote --sandbox --no-mixins
coyote --sandbox --fresh --no-mixins
```
The first run takes a few minutes (building the Coyote sandbox image, installing Rust/uv/build deps, compiling
`coyote-ai`). Subsequent attaches to the same sandbox are instant: Your config, vault state, sessions, OAuth tokens,
and installed tools persist inside the sandbox until you `sbx rm` it.
The first run pulls the pre-built Coyote sandbox image from Docker Hub (`darkalex17/coyote`) and creates the sandbox.
Pull time depends on your connection speed; once the image is cached locally, subsequent sandbox creates are fast.
Attaches to an existing sandbox are instant: your config, vault state, sessions, OAuth tokens, and installed tools
persist inside the sandbox until you `sbx rm` it.
Re-running `coyote --sandbox [NAME]` with the same name **re-attaches** to the existing sandbox silently rather than
creating a fresh one. `--fresh` and `--no-mixins` are ignored on re-attach (they only affect sandbox creation).
@@ -324,8 +325,8 @@ If something looks wrong, these are your three debugging flags:
- **You only need filesystem isolation, not network or process isolation**. sandbox mode trades a few minutes of
first-run setup and ongoing VM overhead (one Docker daemon per sandbox) for full hypervisor isolation. If you only
want to restrict which files Coyote can touch, the existing per-tool permission model is lighter weight.
- **Fast one-off shell commands**. Sandbox attach is fast on warm sandboxes, but cold-start (image + kit installs)
takes minutes. Plain `coyote --execute "..."` on the host is faster for trivial work.
- **Fast one-off shell commands**. Sandbox attach is fast on warm sandboxes, but cold-start (first-time image pull)
takes time.
- **You need to interact with host-only resources** (the host's clipboard, host system services, certain GUI
integrations). Sandboxes can't see the host beyond the mounted workspace and the proxy-mediated network.