Stockyard

Coding agent VM orchestrator. Runs coding agents in isolated Firecracker micro-VMs with ZFS-based audit trail snapshots.

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]

| Flag | Default | Description | |------|---------|-------------| | --name | | Human-readable task name | | --env-file | | Path to .env file to include in the VM | | --env | | Environment variables (KEY=value, repeatable) | | --cpus | 2 | Number of CPU cores | | --memory | 4G | Memory allocation | | --no-tailscale | false | Skip Tailscale setup | | --tailscale-auth-key | | Tailscale auth key (overrides 1Password lookup) |

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 via Firecracker's MMDS metadata service at boot. 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.

Exec and Command Queues (Experimental)

Note: exec and command queues are an experiment in programmatic VM orchestration. The API works 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

Remote Access

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

URL Formats

| Scheme | Description | Example | |--------|-------------|---------| | unix:// | Local Unix socket | unix:///var/run/stockyard/stockyard.sock | | grpc:// | Remote gRPC (no TLS) | grpc://stockyard-server:65433 | | grpcs:// | Remote gRPC with TLS | grpcs://stockyard-server:65433 | | host:port | Defaults to grpc:// | stockyard-server:65433 |

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:

{
  "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).

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

VM Services

VMs include built-in services that communicate with the host via vsock:

| Service | Port | Description | |---------|------|-------------| | stockyard-shell | 52 | Terminal access via vsock (no SSH needed) | | stockyard-snapshot | 51 | ZFS snapshot coordination | | llm-proxy | 12071 | LLM API logging proxy (routes Anthropic/OpenAI traffic) |

Terminal Access

The dashboard provides browser-based terminal access to VMs using stockyard-shell. This eliminates SSH key management and works even when VM networking is misconfigured.

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