sprites-dev

You are managing remote Sprite VMs from a local machine using the sprite CLI. This skill covers the local-side CLI for controlling Sprites externally. (Sprites also have built-in agent context at /.sprite/docs/ for agents running inside the Sprite.)

Sprites are persistent, hardware-isolated Linux VMs on Fly.io with durable filesystems backed by object storage.

CLI Basics

The sprite CLI controls remote Sprites. The -s flag specifies which Sprite, -o specifies the org.

# List all sprites
sprite list
 
# Execute a command on a sprite (blocks until done)
sprite exec -s <name> -- <

When a .sprite file exists in the working directory, -s can be omitted.

Executing Commands

sprite exec is the primary tool for remote work. Stdout and stderr are returned to the local terminal.

Important: Each sprite exec invocation is a separate session. Environment variables, working directory, and shell state do not persist between calls. For stateful work, use bash -c "..." to chain commands, or use sprite console for interactive sessions.

Environment variables: The -env flag passes env vars to the remote session, but multiple -env flags only apply the last one. Use comma-separated format for multiple vars:

File Transfer

There is no dedicated file transfer command. Use sprite exec with cat for pulling files, or pipe content in:

Checkpoints

Checkpoints capture the writable overlay of the Sprite's filesystem. They are fast (sub-second, copy-on-write) and cheap.

Checkpoint aggressively. Before any risky operation, before switching contexts, whenever something is working. Checkpoints are nearly free.

The last 5 checkpoints are also mounted inside the Sprite at /.sprite/checkpoints/ for direct file-level inspection without restoring.

Networking

Each Sprite gets a public HTTPS URL at https://<name>-<org>.sprites.dev/, routing to port 8080 by default.

Network egress policy is managed via the Sprites REST API, not the CLI:

Network policy can only be modified externally. The Sprite cannot change its own policy.

Services

Services are long-running processes inside a Sprite that persist across reboots and hibernation.

One service can be designated as the HTTP service (receives proxied requests on the Sprite's URL).

Multi-Sprite Coordination

When working across multiple Sprites, use sprite list to see the fleet, then target each by name:

Each Sprite is fully isolated — no shared mutable state. Coordinate through explicit communication: files in shared Tigris buckets, HTTP endpoints, or Git repos.

Lifecycle

Sprites auto-sleep when idle (no active commands, TCP connections, TTY sessions, or running Services). They wake automatically on the next sprite exec, sprite console, or HTTP request to their URL. Anything on disk persists across sleep cycles. Running processes do not — use Services for daemons.

Setting Up a Dev Sprite

After creating a new Sprite, set up Tailscale and install dotfiles. Tailscale provides a stable hostname for SSH and enables agent forwarding from the Mac's 1Password SSH agent.

1. Install Tailscale and dotfiles

Pass TS_AUTHKEY and TS_HOSTNAME so install.sh handles Tailscale end-to-end:

Verify SSH connectivity from the Mac:

Do not proceed until this succeeds.

2. Clone project repos

The Mac's SSH config forwards the 1Password agent to *.ts.net hosts (ForwardAgent yes). This means ssh <name> gives the Sprite access to your GitHub SSH keys — no tokens needed. Clone directly:

Git commit signing is automatically enabled on first login via Tailscale SSH (the shell detects the forwarded agent).

3. Connect from Zed

Internal Sprite Paths

When running commands on a Sprite, these paths are useful:

• /.sprite/api.sock — internal API Unix socket
• /.sprite/policy/network.json — read-only network policy
• /.sprite/checkpoints/ — last 5 checkpoints mounted for inspection
• /.sprite/logs/services/ — service logs
• /.sprite/docs/ — platform documentation (agent-context.md, languages.md, docker.md)
• /home/sprite/ — user home directory