Sprites

A sprite is a persistent, hardware-isolated Linux environment. It keeps its filesystem between sessions, gets a public hostname, runs services that survive disconnects, and can be snapshotted and restored in seconds.

Before anything else, work out where you are running. Every operation has two forms, and picking the wrong one wastes a turn.

Step 1: detect the context

test -S /.sprite/api.sock && echo inside || echo outside

Cache the answer for the session; it cannot change mid-session.

The two control planes are not interchangeable:

• sprite-env talks to the local API socket. It always acts on this sprite and takes no sprite name. It cannot see or touch other sprites.
• sprite talks to https://api.sprites.dev over the network. Nearly every command needs a target sprite (-s <name>), and it can create and destroy sprites.

Do not call sprite-env from outside a sprite, and do not use the remote MCP tools or sprite -s <self> from inside a sprite to manage the sprite you are already in. See environment detection for the fallbacks when neither binary is installed.

Step 2: pick the smallest operation

Golden path

1. Detect inside or outside. Choose the control plane once.
2. Identify the exact sprite by name. From outside, get it from sprite list or from .sprite/config (sprite use); never guess a name.
3. Inspect before you mutate. Read service state, logs, or checkpoint lists first.
4. Checkpoint valuable state before risky work. Checkpoints take seconds.
5. Do the work: exec for bounded commands, a service for anything that must outlive the call.
6. Verify with real output — exit status, service state, logs, an HTTP probe.
7. Report the sprite name, the URL and its auth mode, and any checkpoint IDs.

Safety rules

• A sprite URL may be public. Never serve environment variables, tokens, key files, unfiltered logs, or admin endpoints from a sprite service.
• checkpoint restore rewinds the filesystem and discards later changes. Explain that and get approval before running it.
• destroy is irreversible and takes the services, checkpoints, and URL with it. Require explicit intent.
• Network policy updates replace the whole rule set. Read the current policy, merge, then write.

Full detail in safety.

References

Read the one that matches the task; each is self-contained.

• environment-detection.md — deciding inside vs outside, installing either CLI, and auth setup.
• remote.md — driving sprites from outside: create, list, exec, sessions, files, ports, destroy.
• services.md — long-running processes, the service manager, and the public HTTP URL.
• checkpoints.md — snapshots, rollback, and reading old files from mounted checkpoints.
• network-policy.md — outbound egress rules and the read-modify-write update procedure.
• api-gateway.md — third-party APIs (GitHub, Slack, …) with credentials injected by the gateway.
• cli.md — the full sprite-env and sprite command surface.
• http-api.md — REST endpoints behind both CLIs, for agents with only an HTTP client.
• files.md — moving code and data in and out.
• safety.md — confirmation rules and exposure limits.