Stockyard

Coding agent VM orchestrator. Runs coding agents in isolated VMs — Firecracker micro-VMs on Linux (with ZFS-based audit-trail snapshots), and Apple's container tool on macOS.

Quick Start

# Initialize stockyard
stockyard init --instance my-dev

# Start the daemon (in another terminal)
stockyardd

# Create a VM
stockyard run --name my-task --env-file .env

# Attach to the running VM
stockyard attach <task-id>

# List running tasks
stockyard list

Creating VMs

stockyard run [flags]

SSH public keys from ~/.ssh/*.pub are automatically injected into the VM.

Environment Configuration

The --env-file flag delivers a .env file into the VM at boot. The Firecracker backend ships it via the MMDS metadata service; the apple-container backend forwards it as container run --env flags (explicit task env overrides .env entries). Either way, this is the primary way to pass API keys and tokens.

Tailscale auth keys are handled separately via --tailscale-auth-key or automatic 1Password lookup.

Remote Access

The CLI can connect to remote stockyard daemons using the --url flag or STOCKYARD_URL environment variable.

URL Formats

Examples

# Connect to a remote daemon via flag
stockyard --url grpc://stockyard-server:65433 list

# Or via environment variable
export STOCKYARD_URL=grpc://stockyard-server:65433
stockyard list

# Shell alias for frequent remote access
alias stockyard-prod='stockyard --url grpc://stockyard-prod:65433'
stockyard-prod list

Connection Resolution

The CLI resolves the daemon connection in this order:

1. --url flag (highest priority)
2. STOCKYARD_URL environment variable
3. System config (/etc/stockyard/config.json socket path)
4. Default: unix:///var/run/stockyard/stockyard.sock

Daemon Configuration

To enable remote access, configure the daemon to listen on TCP:

{
  "backend": "firecracker",
  "daemon": {
    "socket_path": "/var/run/stockyard/stockyard.sock",
    "grpc_addr": ":65433"
  }
}

When grpc_addr is set, the daemon listens on both the Unix socket (for local access) and TCP (for remote access).

The top-level backend key selects the VM backend. Valid values are "firecracker" (default, Linux) and "apple-container" (macOS). The apple-container backend skips the Firecracker-only setup steps — no ZFS, no kernel/rootfs install — and uses Apple's container CLI to manage VMs.

Note: For secure remote access, use Tailscale or a reverse proxy with TLS. The daemon does not yet support TLS directly.

VM Services

VMs ship with llm-proxy (port 12071) — an outbound HTTP proxy that logs Anthropic/OpenAI API traffic. It runs in-guest on both backends.

Terminal access and snapshot coordination work differently per backend:

Both vsock services exist because Firecracker VMs are otherwise isolated from the host. On apple-container, native container tooling covers the same needs — so neither guest binary is built into or needed in the apple-container image.

See docs/specs/vsock-shell-service.md for the Firecracker vsock-shell protocol.

Exec and Command Queues (Experimental, Linux only)

Note: exec and command queues are an experiment in programmatic VM orchestration, and only the Firecracker backend implements them. The API works and has proven useful from time to time, but it's not clear this is the right abstraction — running commands via SSH into the VM's Tailscale address is simpler and may be the better pattern. This interface may change significantly or be removed.

stockyard exec runs commands inside a VM:

stockyard exec <task-id> -- go mod download
stockyard exec <task-id> -- claude-code -p "implement OAuth"

Commands are managed through named queues. Two are created automatically with each VM:

• default — serial execution. Commands run one at a time.
• admin — concurrent. For interactive/debug shells.

stockyard queue list <task-id>
stockyard queue status <task-id> default
stockyard command logs <task-id> <command-id> --follow