From 8bf06911de06e1cdfbe841198fec4e1a7d3ffca9 Mon Sep 17 00:00:00 2001
From: Alex Clarke <alex.j.tusa@gmail.com>
Date: Wed, 1 Jul 2026 18:55:24 -0600
Subject: [PATCH] docs: Added documentation on how to run multiple sandboxes in
 one directory

---
 Sandboxes.md | 38 ++++++++++++++++++++++++++++++++------
 1 file changed, 32 insertions(+), 6 deletions(-)

diff --git a/Sandboxes.md b/Sandboxes.md
index 81ec4fe..4c154fc 100644
--- a/Sandboxes.md
+++ b/Sandboxes.md
@@ -35,6 +35,23 @@ 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).
 
+### Multiple sandboxes per workspace
+
+Pass a distinct name for each sandbox you want to keep alive against the same directory. Coyote will treat them as fully 
+independent sbx sandboxes. This is handy for branch-per-sandbox workflows, spike vs. main, or running two Coyote 
+sessions with different vault providers side by side:
+
+```bash
+# From ~/code/my-project
+coyote --sandbox feature-branch   # create/attach to sandbox 'feature-branch'
+coyote --sandbox spike            # create/attach to sandbox 'spike'
+coyote --sandbox review           # create/attach to sandbox 'review'
+```
+
+`sbx ls` shows each one. Manage them individually with `sbx stop <NAME>`, `sbx rm <NAME>`, etc. The bare 
+`coyote --sandbox` (no name) still resolves to the current directory basename, so treat that as your default sandbox 
+and use explicit names for the rest.
+
 > **Tip:** Inside the sandbox REPL, prefix any line with `!` to run a shell command without going through `sbx exec 
 > <name> -- <cmd>` to modify the sandbox state; .e.g, `!apt-get update`, `!git pull`, `!cargo build`, etc. Output 
 > streams to your terminal, Ctrl-C interrupts long-running commands, and you don't spend any tokens because no output is
@@ -63,22 +80,31 @@ sbx ls
 
 # 5. If not, create it with the base kit + every discovered mixin layered on
 sbx create \
+  --name <NAME> \
   --kit <cache>/sbx-kit/ \
   --kit <vault-provider-mixin-if-any> \
   --kit <user-mixin-1> \
   --kit <user-mixin-N> \
-  coyote --name <NAME> .
+  coyote .
 
-# 6. Copy your host config into the sandbox (skipped if --fresh)
-sbx exec <NAME> sh -c "sudo mkdir -p /home/agent/.config && sudo chown agent:agent /home/agent/.config"
-sbx cp ~/.config/coyote/ <NAME>:/home/agent/.config/
+# 6. Copy your host config into the sandbox (skipped if --fresh). Each top-level
+#    entry is copied individually to sidestep a macOS `docker cp` quirk that
+#    silently drops files carrying `com.apple.provenance` xattrs when they're
+#    tarred as part of a recursive directory copy.
+sbx exec <NAME> sh -c "sudo mkdir -p /home/agent/.config/coyote && sudo chown agent:agent /home/agent/.config/coyote"
+for entry in ~/.config/coyote/*; do
+  sbx cp "$entry" <NAME>:/home/agent/.config/coyote/
+done
+sbx exec <NAME> sh -c "sudo chown -R agent:agent /home/agent/.config/coyote"
 
 # 7. Copy your vault password file, if a local provider is configured (skipped if --fresh)
 sbx exec <NAME> sh -c "sudo mkdir -p <parent> && sudo chown agent:agent <parent>"
 sbx cp <host-password-file> <NAME>:<destination>
+sbx exec <NAME> sh -c "sudo chown -R agent:agent <destination>"
 
-# 8. Hand control to sbx (Coyote's process is replaced)
-exec sbx run <NAME> --kit <cache>/sbx-kit/
+# 8. Hand control to sbx (Coyote's process is replaced). `--kit` is re-passed
+#    on reattach because sbx expects it even when the sandbox already exists.
+exec sbx run --name <NAME> --kit <cache>/sbx-kit/
 ```
 
 Once `sbx run` takes over, Coyote on the host exits and your terminal is connected to Coyote inside the sandbox. All