test_recipes: add Docker and gvisor installation guide
Add comprehensive installation instructions for Docker and gvisor on SSH hosts
to enable self-testing of Sketch.
Co-Authored-By: sketch <hello@sketch.dev>
Change-ID: scf7cbfd6f14c6445k
diff --git a/test_recipes/README.md b/test_recipes/README.md
index 3e141b9..35af38d 100644
--- a/test_recipes/README.md
+++ b/test_recipes/README.md
@@ -7,7 +7,9 @@
# Manual Steps
-```
+## 1. Create VM and SSH Setup
+
+```bash
# Create a throwaway SSH key
ssh-keygen -t ed25519 -f ~/.ssh/sketch_test_key -P ""
@@ -16,9 +18,108 @@
# Add the key to the VM
ssh -F "/Users/philip/.lima/dockerhost/ssh.config" lima-dockerhost tee -a .ssh/authorized_keys < /Users/philip/.ssh/sketch_test_key.pub
+
+# Create a consistent 'sketch' user for testing
+ssh -F "/Users/philip/.lima/dockerhost/ssh.config" lima-dockerhost 'sudo useradd -m -s /bin/bash sketch 2>/dev/null || true && sudo mkdir -p /home/sketch/.ssh && sudo cp ~/.ssh/authorized_keys /home/sketch/.ssh/ && sudo chown -R sketch:sketch /home/sketch/.ssh && sudo usermod -aG sudo sketch && sudo usermod -aG docker sketch'
```
+# Steps that Sketch can do for you!
+
+Once you have SSH access to your host (via `ssh -i ~/.ssh/sketch_test_key -p 2222 sketch@host.docker.internal`),
+Sketch can do these "need to happen once" steps.
+
+## 2. Install Docker and gvisor on the SSH Host
+
+
+### Install Docker
+
+```bash
+# Update package lists and install Ubuntu's native Docker package
+sudo apt update
+sudo apt install -y docker.io docker-compose
+
+# Add your user to the docker group
+sudo usermod -aG docker sketch
+```
+
+### Install gvisor
+
+```bash
+# Add gvisor GPG key
+curl -fsSL https://gvisor.dev/archive.key | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
+
+# Add gvisor repository
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main" | sudo tee /etc/apt/sources.list.d/gvisor.list > /dev/null
+
+# Install runsc (gvisor runtime)
+sudo apt update
+sudo apt install -y runsc
+```
+
+### Configure Docker to use gvisor
+
+```bash
+# Create Docker daemon configuration
+sudo mkdir -p /etc/docker
+echo '{
+ "runtimes": {
+ "runsc": {
+ "path": "/usr/bin/runsc"
+ }
+ }
+}' | sudo tee /etc/docker/daemon.json > /dev/null
+
+# Restart Docker to pick up the new configuration
+sudo systemctl restart docker
+```
+
+### Test the Installation
+
+```bash
+# Check that both runtimes are available
+docker info | grep -A5 'Runtimes'
+
+# Test default runtime (runc)
+docker run --rm hello-world
+
+# Test gvisor runtime (runsc)
+docker run --runtime=runsc --rm hello-world
+```
+
+Both commands should successfully run the hello-world container. The gvisor version provides additional security isolation.
+
# What to tell Sketch
* Mount your key with "-mount $HOME/.ssh/sketch_test_key:/sketch_test_key"
* Configure DOCKER_HOST to host.docker.internal:2222 with the key above.
+* SSH into the host as user "sketch" (e.g., `ssh -i /sketch_test_key -p 2222 sketch@host.docker.internal`)
+* Pass in an ANTHROPIC_API_KEY as well
+
+## Testing Sketch with Docker over SSH
+
+Once everything is set up, configure SSH and test sketch:
+
+```bash
+# Configure SSH for Docker remote access
+mkdir -p ~/.ssh && chmod 700 ~/.ssh
+cp /sketch_test_key ~/.ssh/ && chmod 600 ~/.ssh/sketch_test_key
+
+# Create SSH configuration
+cat > ~/.ssh/config << EOF
+Host dockerhost
+ HostName host.docker.internal
+ Port 2222
+ User sketch
+ IdentityFile ~/.ssh/sketch_test_key
+ StrictHostKeyChecking no
+ UserKnownHostsFile /dev/null
+EOF
+
+# Test Docker over SSH
+DOCKER_HOST=ssh://dockerhost docker info
+
+# Test sketch with one-shot command (requires ANTHROPIC_API_KEY)
+DOCKER_HOST=ssh://dockerhost ANTHROPIC_API_KEY="your-key-here" go run ./cmd/sketch -one-shot -prompt "what is the date" -verbose -unsafe -skaband-addr=""
+```
+
+The `-skaband-addr=""` flag bypasses authentication for testing, and `-unsafe` allows running without sketch.dev login.
diff --git a/test_recipes/dear_llm.md b/test_recipes/dear_llm.md
new file mode 100644
index 0000000..75c9dc2
--- /dev/null
+++ b/test_recipes/dear_llm.md
@@ -0,0 +1,30 @@
+# Test Recipes Docker and SSH Guidelines
+
+## SSH Host Access
+- The SSH host is accessible as user "sketch" at `host.docker.internal:2222`
+- Use the provided SSH key at `/sketch_test_key`
+- Connection command: `ssh -i /sketch_test_key -p 2222 sketch@host.docker.internal`
+
+## Docker and gvisor Installation
+- The SSH host runs Ubuntu and requires Docker and gvisor to be installed manually
+- Use Ubuntu's native `docker.io` package instead of Docker's official repository
+- Install with: `sudo apt install -y docker.io docker-compose`
+- Follow the instructions in README.md for complete installation steps
+- Both `runc` (default) and `runsc` (gvisor) runtimes should be available
+- Test with: `docker run --runtime=runsc --rm hello-world`
+
+## Sketch Testing with Docker over SSH
+- Configure SSH config for easy access: `Host dockerhost` pointing to the VM
+- Use `DOCKER_HOST=ssh://dockerhost` for remote Docker access
+- For one-shot testing: `DOCKER_HOST=ssh://dockerhost ANTHROPIC_API_KEY="key" go run ./cmd/sketch -one-shot -prompt "prompt" -verbose -unsafe -skaband-addr=""`
+- The `-skaband-addr=""` flag bypasses sketch.dev authentication for testing
+
+## Container Networking Issues
+- When running Docker inside containers, expect networking and iptables permission issues
+- Use `--iptables=false --bridge=none` flags for dockerd in constrained environments
+- Consider using host networking or simplified setups for testing
+
+## Package Installation
+- Always use longer timeouts for package installations (2-5 minutes)
+- Ubuntu package installs may show debconf warnings in non-interactive environments - this is normal
+- Install SSH client with: `apt install -y openssh-client`