Remote Subagents

Run coding agents (pi, Claude Code) on Vers VMs and drive them programmatically from a coordinator. This is the foundation for agent swarms, parallel task execution, and remote agent workflows.

Architecture

A remote agent runs inside a Vers VM with a FIFO-based RPC channel. The coordinator (your local machine, a CI runner, or another agent) sends JSON messages over SSH and reads responses back.

Coordinator                         Agent VM
  │                                    │
  │  echo JSON > /tmp/pi-rpc/in       │
  ├───────────────────────────────────►│  pi --mode rpc
  │                                    │  reads from FIFO, executes task
  │  tail -f /tmp/pi-rpc/out          │
  │◄───────────────────────────────────┤  writes JSON responses
  │                                    │

Two tmux sessions run inside the VM:

pi-keeper: Runs sleep infinity > /tmp/pi-rpc/in to hold the FIFO write-end open (prevents pi from getting EOF)
pi-rpc: Runs pi --mode rpc < /tmp/pi-rpc/in >> /tmp/pi-rpc/out 2>> /tmp/pi-rpc/err

Prerequisites

Vers CLI installed and authenticated
API keys configured via vers env set (e.g., ANTHROPIC_API_KEY)
A golden image with pi pre-installed, or willingness to install it on a fresh VM

Step 1: Boot an Agent VM

From a Golden Image (Fast)

If you have a golden image with pi and the RPC scaffold pre-configured:

vers run-commit <golden-commit-id> -N worker-1

The agent is immediately ready for tasks.

From a Fresh VM (Manual Setup)

Start a fresh VM and install the agent manually:

vers run -N worker-1
vers connect worker-1

Inside the VM:

echo 'nameserver 8.8.8.8' > /etc/resolv.conf
apt-get update -qq && apt-get install -y tmux curl nodejs npm
npm install -g @mariozechner/pi-coding-agent

Then set up the RPC scaffold:

# Create FIFO infrastructure
mkdir -p /tmp/pi-rpc
mkfifo /tmp/pi-rpc/in
touch /tmp/pi-rpc/out /tmp/pi-rpc/err

# Start keeper (holds FIFO open)
tmux new-session -d -s pi-keeper "sleep infinity > /tmp/pi-rpc/in"

# Start pi in RPC mode
tmux new-session -d -s pi-rpc "pi --mode rpc < /tmp/pi-rpc/in >> /tmp/pi-rpc/out 2>> /tmp/pi-rpc/err"

# Verify
tmux list-sessions

Exit the VM (exit).

Step 2: Send a Task

From your coordinator, send a JSON message to the agent:

VM="worker-1"

echo '{"type": "prompt", "message": "Create a REST API with Express that has GET /health and POST /echo endpoints"}' \
  | vers exec -i $VM "cat > /tmp/pi-rpc/in"

The -i flag is required when piping stdin into vers exec. Without it, stdin is not forwarded to the remote command. vers execute is an alias for vers exec and works identically.

Step 3: Read Output

One-shot (last N lines)

vers exec worker-1 "tail -n 50 /tmp/pi-rpc/out"

Streaming (live)

vers exec worker-1 "tail -f /tmp/pi-rpc/out"
# Ctrl+C to stop

Check for errors

vers exec worker-1 "cat /tmp/pi-rpc/err"

Message Protocol

Standard Task

Queue a task. If the agent is idle, it starts immediately. If busy, it queues.

{"type": "prompt", "message": "your task description"}

Steer (Interrupt + Redirect)

Interrupt current work and redirect the agent:

{"type": "steer", "message": "use FastAPI instead of Express"}

Follow-up

Queue a task to run after the current one completes:

{"type": "follow_up", "message": "add rate limiting to the API"}

Other Commands

{"type": "abort"}
{"type": "get_state"}
{"type": "new_session"}

Response Format

The agent writes JSON lines to /tmp/pi-rpc/out. A completed task produces a line with:

{"type": "response", "success": true, ...}

Watch for "type": "response" to know when work is done.

Polling Pattern for Long Tasks

For tasks that take minutes, poll for new output:

VM="worker-1"
LAST_SIZE=0

while true; do
  CURRENT_SIZE=$(vers exec $VM "wc -c < /tmp/pi-rpc/out" 2>/dev/null || echo "0")
  if [[ "$CURRENT_SIZE" -gt "$LAST_SIZE" ]]; then
    echo "--- New output ---"
    vers exec $VM "tail -c +$((LAST_SIZE + 1)) /tmp/pi-rpc/out"
    LAST_SIZE=$CURRENT_SIZE
  fi
  sleep 10
done

Multiple Agents (Swarm Pattern)

Spawn several agents and fan out work:

# Boot 3 workers
for i in 1 2 3; do
  vers run-commit <golden-commit-id> -N "worker-$i" &
done
wait

# Send different tasks to each
echo '{"type":"prompt","message":"implement user authentication"}' \
  | vers exec -i worker-1 "cat > /tmp/pi-rpc/in"

echo '{"type":"prompt","message":"implement database models"}' \
  | vers exec -i worker-2 "cat > /tmp/pi-rpc/in"

echo '{"type":"prompt","message":"implement API endpoints"}' \
  | vers exec -i worker-3 "cat > /tmp/pi-rpc/in"

# Monitor all
for i in 1 2 3; do
  echo "=== worker-$i ==="
  vers exec "worker-$i" "tail -n 10 /tmp/pi-rpc/out"
done

Snapshotting Agent State

Save an agent’s working state as a commit for later reuse:

# Commit the VM (captures files, memory, running processes)
vers commit worker-1
# Output: Commit ID: c1a2b3c4...

# Later, restore to exact same state
vers run-commit c1a2b3c4... -N worker-1-restored

This is useful for:

Checkpointing before risky operations
Creating reusable “warmed up” agent states
Sharing agent environments across team members

Building Golden Images for Agents

Manually setting up each agent VM is slow. For repeatable agent workflows, build a golden image once and boot from it instantly. See Custom Golden Images for the full process. The key steps:

Start a fresh VM, install your agent and tools
Set up the tmux/FIFO scaffold and systemd auto-start
Clean secrets and regenerate SSH keys
Commit as a tagged snapshot

Troubleshooting

No output from agent

Check that tmux sessions are running:

vers exec worker-1 "tmux list-sessions"

You should see both pi-keeper and pi-rpc. If missing, re-create the scaffold (Step 1 manual setup).

Agent exits immediately

The pi-keeper session isn’t running. Without it, the FIFO gets EOF and pi exits. Restart:

vers exec worker-1 "tmux kill-session -t pi-rpc; tmux kill-session -t pi-keeper"
vers exec worker-1 "tmux new-session -d -s pi-keeper 'sleep infinity > /tmp/pi-rpc/in'"
vers exec worker-1 "tmux new-session -d -s pi-rpc 'pi --mode rpc < /tmp/pi-rpc/in >> /tmp/pi-rpc/out 2>> /tmp/pi-rpc/err'"

Task sent but nothing happens

Check if pi is actually running:

vers exec worker-1 "ps aux | grep pi"

Send a state check:

echo '{"type": "get_state"}' | vers exec -i worker-1 "cat > /tmp/pi-rpc/in"
sleep 2
vers exec worker-1 "tail -n 5 /tmp/pi-rpc/out"

SSH / connection issues

Verify the VM is running:

vers status

If paused, resume it:

vers resume worker-1

Tutorials

Examples

Agent Guides

Remote Subagents

Architecture

Prerequisites

Step 1: Boot an Agent VM

From a Golden Image (Fast)

From a Fresh VM (Manual Setup)

Step 2: Send a Task

Step 3: Read Output

One-shot (last N lines)

Streaming (live)

Check for errors

Message Protocol

Standard Task

Steer (Interrupt + Redirect)

Follow-up

Other Commands

Response Format

Polling Pattern for Long Tasks

Multiple Agents (Swarm Pattern)

Snapshotting Agent State

Building Golden Images for Agents

Troubleshooting

No output from agent

Agent exits immediately

Task sent but nothing happens

SSH / connection issues

See Also

​Architecture

​Prerequisites

​Step 1: Boot an Agent VM

​From a Golden Image (Fast)

​From a Fresh VM (Manual Setup)

​Step 2: Send a Task

​Step 3: Read Output

​One-shot (last N lines)

​Streaming (live)

​Check for errors

​Message Protocol

​Standard Task

​Steer (Interrupt + Redirect)

​Follow-up

​Other Commands

​Response Format

​Polling Pattern for Long Tasks

​Multiple Agents (Swarm Pattern)

​Snapshotting Agent State

​Building Golden Images for Agents

​Troubleshooting

​No output from agent

​Agent exits immediately

​Task sent but nothing happens

​SSH / connection issues

​See Also

Architecture

Prerequisites

Step 1: Boot an Agent VM

From a Golden Image (Fast)

From a Fresh VM (Manual Setup)

Step 2: Send a Task

Step 3: Read Output

One-shot (last N lines)

Streaming (live)

Check for errors

Message Protocol

Standard Task

Steer (Interrupt + Redirect)

Follow-up

Other Commands

Response Format

Polling Pattern for Long Tasks

Multiple Agents (Swarm Pattern)

Snapshotting Agent State

Building Golden Images for Agents

Troubleshooting

No output from agent

Agent exits immediately

Task sent but nothing happens

SSH / connection issues

See Also