From 8293cab119d76fbaa48bc9b6e1dd0bba0cd01127 Mon Sep 17 00:00:00 2001
From: Alex Clarke <alex.j.tusa@gmail.com>
Date: Wed, 15 Jul 2026 13:20:56 -0600
Subject: [PATCH] docs: Added docs for the new docker image and sandbox that
 uses the image to run

---
 Installation.md | 26 ++++++++++++++++++++++++++
 Sandboxes.md    | 11 ++++++-----
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/Installation.md b/Installation.md
index ac1e72a..ae15631 100644
--- a/Installation.md
+++ b/Installation.md
@@ -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
diff --git a/Sandboxes.md b/Sandboxes.md
index 4c154fc..531e610 100644
--- a/Sandboxes.md
+++ b/Sandboxes.md
@@ -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.