devsh - Cloud VMs for Development

Note: devsh can be installed via npm for production use, or built from local source (packages/devsh) when developing or testing the CLI itself.

Pre-flight Check

Before using devsh commands, verify installation:

which devsh || ~/.local/bin/devsh --version

# If not found, build and install from source:
make install-devsh-dev

Quick Start

devsh auth login              # Authenticate (opens browser)
devsh start ./my-project      # Create VM, sync directory
devsh start -p pve-lxc .      # Create VM with PVE LXC provider
devsh code <id>               # Open VS Code in browser
devsh ssh <id>                # SSH into VM
devsh exec <id> "npm run dev" # Run commands
devsh pause <id>              # Pause VM
devsh resume <id>             # Resume VM
devsh delete <id>             # Delete VM
devsh ls                      # List all VMs

Provider Selection

# Explicit provider
devsh start -p morph .        # Use Morph
devsh start -p pve-lxc .      # Use PVE LXC (self-hosted)

# Auto-detect from environment
export PVE_API_URL=https://pve.example.com
export PVE_API_TOKEN=root@pam!token=secret
devsh start .                 # Auto-selects pve-lxc when PVE env vars are set

Commands

Authentication

• devsh auth login - Login via browser
• devsh auth logout - Clear credentials
• devsh auth status - Show authentication status
• devsh auth whoami - Show current user
• devsh login - Shorthand for auth login
• devsh logout - Shorthand for auth logout
• devsh whoami - Shorthand for auth whoami

VM Lifecycle

• devsh start [path] - Create VM, optionally sync directory
• devsh start -p <provider> - Specify provider (morph, pve-lxc)
• devsh pause <id> - Pause VM
• devsh resume <id> - Resume VM
• devsh delete <id> - Delete VM
• devsh ls - List VMs
• devsh status <id> - Show VM status and URLs

Access VM

• devsh code <id> - Open VS Code in browser
• devsh vnc <id> - Open VNC desktop
• devsh ssh <id> - SSH into VM

Work with VM

• devsh exec <id> "<cmd>" - Run command
• devsh sync <id> <path> - Sync files to VM
• devsh sync <id> <path> --pull - Pull files from VM

Task Management

Tasks are the same as in the web app dashboard. CLI and web sync through Convex.

• devsh task list - List active tasks
• devsh task list --archived - List archived tasks
• devsh task create --repo owner/repo --agent claude-code "prompt" - Create task
• devsh task create --cloud-workspace ... - Create as cloud workspace (appears in Workspaces section)
• devsh task show <task-id> - Get task details and runs
• devsh task stop <task-id> - Stop/archive task
• devsh task memory <task-run-id> - View agent memory for a task run

Notes:

• devsh task create uses a positional prompt argument. --prompt is not a valid flag.
• For automation, prefer --json and poll with devsh task show <task-id> or devsh task list after creation.

Task Workflow: Branches and Pull Requests

Important: Each task run automatically creates a new branch. Changes are NOT made to your existing branch.

Branch Behavior

• Each task creates a new branch: {prefix}{task-slug}-{random-id}
• The branch prefix defaults to dev/ and is user-configurable in web UI Settings > Git
• Example: devsh task create "Fix login bug" creates branch dev/fix-login-bug-x8k3a
• Changes are committed and pushed to this new branch automatically

Auto-PR (Disabled by Default)

When all agents complete, the system:

1. Crown evaluation: Compares agent outputs and selects the best diff (winner)
2. Push: Pushes the winning branch to the remote repository
3. PR creation: Only if "Auto-PR" is enabled in Settings > General

To enable Auto-PR:

1. Open web UI (cmux.app or your deployment)
2. Go to Settings > General
3. Enable "Auto-create pull request with the best diff"

To manually create a PR after task completion:

# View the task to find the winning branch
devsh task show <task-id>

# Create PR manually with gh CLI
gh pr create --head dev/your-branch-name --title "Your PR title"

Single-Agent vs Multi-Agent Tasks

• Single agent: Auto-crowned immediately when completed
• Multi-agent (Crown): Evaluates all diffs, crowns the best solution, then pushes

Agent Memory

View agent memory snapshots synced from sandboxes when agents complete.

devsh task memory <task-id>              # View memory (uses latest run)
devsh task memory <task-run-id>          # View specific run's memory
devsh task memory <task-id> -t knowledge # Filter by type
devsh task memory <task-id> -t daily     # Daily logs only
devsh task memory <task-id> --json       # JSON output

Accepts either task ID (p17...) or task run ID (ns7...). Memory types: knowledge, daily, tasks, mailbox

Team Management

• devsh team list - List your teams
• devsh team switch <team-slug> - Switch to a different team

Agent Management

• devsh agent list - List available coding agents

GitHub Projects (v2)

Import markdown plans into GitHub Projects as draft issues. Note: Only organization projects work - user-owned projects don't work with GitHub Apps.

• devsh project import <file> --project-id <id> --installation-id <id> - Import plan as draft issues
• devsh project import <file> --project-id <id> --dry-run - Preview without importing

# Get project ID
gh project list --owner <org> --format json | jq '.projects[].id'

# Import plan (H2 sections become draft issues)
devsh project import ./plan.md --project-id PVT_xxx --installation-id 12345

Browser Automation

• devsh computer snapshot <id> - Get accessibility tree
• devsh computer open <id> <url> - Navigate browser
• devsh computer click <id> @e1 - Click element
• devsh computer screenshot <id> - Take screenshot

Building from Source

# From repo root
make install-devsh-dev

# Or manually
cd packages/devsh
make build-dev
cp bin/devsh ~/.local/bin/

Environment Variables

Create Symlinks for Other Agents

mkdir -p .claude/skills
ln -s ../../.agents/skills/devsh .claude/skills/devsh