Sandbox Exe Dev

Agent Sandboxes (exe.dev)

This skill is the persistent-VM cousin of /agent-sandboxes (the E2B skill, installed globally at ~/.claude/skills/agent-sandboxes/). It gives an agent the same ergonomic CLI surface (exedev init, exedev exec, exedev files, exedev share, exedev browser) but backs it with exe.dev's persistent VMs over SSH instead of E2B's ephemeral sandboxes.

If you already know /agent-sandboxes, the sbx → exedev mapping below covers 90% of the muscle memory. The 10% that doesn't translate is documented honestly — pause, extend-lifetime, and template registries don't exist on exe.dev; in exchange you get persistent disks, live resize, whole-VM snapshot, and an auth-gated HTTPS proxy.

Variables

• EXEDEV_CLI_PATH: .claude/skills/sandbox-exe-dev/exedev_cli/
• LOCAL_WORKSPACE: tmp/<workflow_id>/ — local staging for files to upload/download. Create when needed.
• WORKFLOW_ID: kebab-case identifier for the current task. Generate as <task>-<YYYYMMDD>-<short-uuid> if the user doesn't provide one (e.g. todo-app-20260508-7f3a). The VM name should derive from this.
• TIMEOUT_DURATION_IN_SECONDS: N/A on exe.dev — VMs are persistent and never auto-expire. Tear down with exedev vm kill <name> when truly done.

Prerequisites

Before using this skill, validate the environment:

1. Check SSH access to exe.dev:

   cd EXEDEV_CLI_PATH
   uv run exedev doctor

   Expected output ends with doctor: OK. If it doesn't:

   • First-ever SSH? Verify the host-key fingerprint matches SHA256:JJOP/lwiBGOMilfONPWZCXUrfK154cnJFXcqlsi6lPo (source: ai_docs/exedev/faq-host-key.md).
   • Permission denied? Make sure your SSH public key is registered: cat ~/.ssh/id_ed25519.pub | ssh exe.dev ssh-key add.
   • Wrong key picked up? Add a stanza to ~/.ssh/config:

     Host exe.dev *.exe.xyz
       IdentitiesOnly yes
       IdentityFile ~/.ssh/id_ed25519_exe

2. Verify the CLI is installed:

   cd EXEDEV_CLI_PATH
   uv sync --quiet
   uv run exedev --help

Instructions

• VMs are persistent. Unlike E2B, an exe.dev VM lives until you exedev vm kill <name> it. Forgotten VMs continue billing — clean up.
• Names matter. A VM's name becomes its public URL: <name>.exe.xyz. Pick names that are unique to your workflow (<workflow_id>-<short-uuid>). Two agents using myvm will collide.
• Track the VM name in your context — not in shell variables, not in a file. Multi-agent safe.
• Login user is exedev, home is /home/exedev. Use --root (sudo) for system-level operations.
• URLs are private by default. https://<name>.exe.xyz/ redirects unauthenticated users to exe.dev login. To match E2B's "anyone with the URL" behaviour, run exedev share set-public <name>. (See Step 5 of the workflow.)
• Use SSH, not the HTTPS API. The POST https://exe.dev/exec endpoint has a 30s timeout and 64KB body cap; this CLI deliberately avoids it. Direct SSH (ssh <vm>.exe.xyz "<cmd>") has neither.
• Don't create files locally — write them on the VM with exedev files write … --stdin or exedev exec … "cat > path" --stdin. Use LOCAL_WORKSPACE only when you actually need a local artifact.

CLI overview

The exedev CLI has six core command groups plus three top-level helpers. The shape mirrors sbx from /agent-sandboxes:

1. exedev init — quick VM creation (mirrors sbx init).
2. exedev vm — lifecycle (list, info, stat, kill, restart, rename, resize, tag, comment, snapshot).
3. exedev exec — run a command on a VM (mirrors sbx exec).
4. exedev files — file ops (mirrors sbx files; transparent SSH/SCP/RSYNC).
5. exedev share — port exposure & access control (unique-to-exe.dev surface, plus share get-host for ergonomic parity with sbx sandbox get-host).
6. exedev browser — local Playwright + CDP browser automation (lifted verbatim from /agent-sandboxes; same flags, same semantics).

Helpers:

• exedev doctor — smoke-test the SSH-to-exe.dev pipeline.
• exedev whoami — show your account + registered SSH keys.

Get help on any command:

cd EXEDEV_CLI_PATH
uv run exedev --help                # top-level
uv run exedev <group> --help        # e.g. uv run exedev vm --help
uv run exedev <group> <verb> --help # e.g. uv run exedev files write --help

Mapping: sbx → exedev

The full per-row parity table with parity-status counts is at /tmp/sandbox-parity/AGENT_SANDBOXES_FEATURE_PARITY.md (artifact of the parity exercise that produced this skill).

Workflow

Step 1: Validate environment

cd EXEDEV_CLI_PATH
uv run exedev doctor

If doctor: OK, proceed. Otherwise see the Troubleshooting section.

Step 2: Generate workflow_id and VM name

Pick a kebab-case workflow ID; derive the VM name from it. Both agents and humans should be able to read these.

workflow_id = "todo-app-20260508-7f3a"
vm_name     = workflow_id   # name == public URL: https://todo-app-20260508-7f3a.exe.xyz/

Step 3: Create the VM

cd EXEDEV_CLI_PATH
uv run exedev init --name <vm_name>
# Optional: --image ubuntu:22.04 --cpu 4 --memory 8GB --disk 20GB
# Optional: --tag <tag> --env KEY=VAL --no-shelley

Boot is ~2s. Capture the name in your context (the CLI prints it; you chose it).

# If you'll need local file staging:
mkdir -p tmp/<workflow_id>

Step 4: Operate on the VM

Run commands (mirrors sbx exec):

uv run exedev exec <vm_name> "uname -a"
uv run exedev exec <vm_name> "pip install requests" --root --timeout 120
uv run exedev exec <vm_name> "ls" --cwd /home/exedev/project
uv run exedev exec <vm_name> "echo \$FOO" --env FOO=bar --shell

Files:

# Write (use --stdin for complex content with brackets/quotes/globs)
echo 'print("hello")' | uv run exedev files write <vm_name> /home/exedev/hello.py --stdin

# Read
uv run exedev files read <vm_name> /home/exedev/hello.py

# Literal-string edit (matches E2B `files edit` exactly)
uv run exedev files edit <vm_name> /home/exedev/config.toml --old "debug = false" --new "debug = true"

# Binary upload/download (scp under the hood)
uv run exedev files upload <vm_name> tmp/<workflow_id>/image.png /home/exedev/image.png
uv run exedev files download <vm_name> /home/exedev/output.pdf tmp/<workflow_id>/output.pdf

# Recursive transfer (rsync; E2B-parity excludes for .git/.venv/node_modules/etc.)
uv run exedev files upload-dir <vm_name> ./local-project /home/exedev/project
uv run exedev files download-dir <vm_name> /home/exedev/project tmp/<workflow_id>/project

Long-running servers (use --background; no --timeout 0 needed because we detach with nohup):

uv run exedev exec <vm_name> "python -m http.server 5173 --bind 0.0.0.0" --background --cwd /home/exedev/project
# logs land at /tmp/exedev-bg.log on the VM

Step 5: Expose a frontend

This is where exe.dev's model differs most from E2B. Every VM gets https://<vm>.exe.xyz/ for free — but it's private by default (visitors are redirected to exe.dev login).

5.1: Start the server (port 5173 by convention)

uv run exedev exec <vm_name> "npm run dev -- --port 5173 --host 0.0.0.0" --background --cwd /home/exedev/project
# or: "python -m http.server 5173 --bind 0.0.0.0"

The server must bind 0.0.0.0 (not 127.0.0.1) for the proxy to reach it.

5.2: Set the proxy port and (if needed) make it public

# Tell the proxy which port to forward to (default heuristic = Dockerfile EXPOSE).
uv run exedev share port <vm_name> 5173

# Make it anonymously reachable (E2B-equivalent default):
uv run exedev share set-public <vm_name>

# OR: keep it private and grant specific people:
uv run exedev share add <vm_name> teammate@example.com
uv run exedev share add-link <vm_name>          # tokenized link anyone with it can use

5.3: Get the URL

uv run exedev share get-host <vm_name>
# https://<vm_name>.exe.xyz/

uv run exedev share get-host <vm_name> --port 8080
# https://<vm_name>.exe.xyz:8080/   (alternate ports 3000-9999 stay auth-gated)

The URL is deterministic — share get-host simply composes it. (Contrast with sbx sandbox get-host which has to call out to E2B.)

5.4: Verify

curl https://<vm_name>.exe.xyz/
# Or, if you set it public, validate visually:
uv run exedev browser nav https://<vm_name>.exe.xyz/
uv run exedev browser screenshot --path tmp/<workflow_id>/validation.png

Step 6: Tear down (only when truly done)

uv run exedev vm kill <vm_name>

This deletes the persistent disk too. There is no undo. If you might want the state later, snapshot first:

uv run exedev vm snapshot <vm_name> <vm_name>-archive

Cookbook

Examples

Reference

Built-in CLI help:

cd EXEDEV_CLI_PATH
uv run exedev --help                       # all groups
uv run exedev <group> --help               # group-level
uv run exedev <group> <verb> --help        # verb-level

For deeper context:

• EXEDEV_CLI_PATH/README.md — CLI overview and architecture.
• ai_docs/exedev/all.md (in the project that drove the parity exercise) — full exe.dev docs as scraped on 2026-05-08.
• /tmp/sandbox-parity/AGENT_SANDBOXES_FEATURE_PARITY.md — full parity-status table.
• The /agent-sandboxes skill at ~/.claude/skills/agent-sandboxes/ — the E2B counterpart this skill mirrors.