Sprites are great!
I’ve tried using Sprites via several coding agents locally on my system (Claude Code & Copilot). A sprite skill is extremely useful. I think you should write a skill and install it into well-known global skill directories (eg, Claude’s) as part of the install process.
I wrote this skill. It’s a mix of fly.io prose and my own:
$HOME/.claude/skills/sprites/SKILL.md
---
name: sprite
description: Read to understand how to work "on a sprite" or "on sprites"
---
Sprites are a remote VM system optimised for agentic use. You can interact with sprites using the `sprite` command-line tool.
On a sprite, prefer to check out code into a subdirectory of the home directory (eg, `/home/sprite/myproject`).
## Quickstart
Ensure a sprite is ready for use:
- Read the file `.sprite`. If it exists, a default sprite has been created and assigned.
- If not, use `sprite ls` to see if a suitable sprite exists, or create one with `sprite create <name>`. Then assign it to this directory with `sprite use <name>`.
Now you can run commands using `sprite exec -dir myproject go test ./...`.
## Multiple sprites
If you're asked to use multiple sprites, create more as necessary: `for i in $(seq 1 3) ; do sprite create myproject-$i ; done`.
Exec commands on a particular sprite with `-s`: `sprite exec -s myproject-2 git log --oneline -n 5`.
## Checkpoints
Checkpoints are very, very fast. Checkpoint every time you think you're at a good spot. Include a useful comment describing what was accomplished.
Command: `sprite checkpoint create -comment "descriptive comment"
When users indicate something is working, looks good, or is functioning as intended, immediately create a checkpoint to preserve that state with a descriptive comment.
View checkpoints: `sprite checkpoint ls`.
Rollbacks are also fast. Autonomously rollback if the sprite breaks: `sprite restore <id>`.
## Services
- Long-running processes that persist across reboots
- Manage them with `sprite-env` on the sprite itself, eg `sprite exec sprite-env ...`
- Create: `sprite-env services create <name> --cmd <command> [--http-port <port>]` - Only one service can have `--http-port`; it auto-starts on incoming requests
- `--cmd` takes the binary only; pass arguments via `--args`: `--cmd python3 --args "-m,http.server,8080"` - Do NOT start a background process separately — the service manages the process lifecycle
- List/start/stop/restart/delete: `sprite-env services <subcommand>`
- Full help: `sprite-env services --help`
## Further information
Read the following files on any sprite for more information:
- `/.sprite/llm.txt` - platform behavior - `/.sprite/llm-dev.txt` - language runtimes and dev tools
- `/.sprite/logs/services/` - service logs
- `/.sprite/checkpoints/v<X>/` - filesystem snapshot for checkpoint X
Bad: No way to non-interactively exec commands in the background.
sprite exec supports -detachable but this only works for interactive users, as you need to press ctrl-c or ctrl-\ after starting the command. (Side note: this all seems quite buggy on macOS, it reliably crashes on detach and some newlines are eaten.)
I wish there was a way to start commands in the background and then poll for the most recent N lines of output:
$ spacectl exec -background yes
job id: 1
$ spacectl exec-logs -n 3 1
y
y
y
$ spacectl exec-kill 1
Bad: No easy way to check if a default sprite has been assigned.
The agent can check for .sprite file, but this is awkward. The file might be in a parent directory. Agents also get confused reading it:
⏺ Read(.sprite)
⎿ Read 4 lines
⏺ Bash(sprite ls)
⎿ XXX
myproject
⏺ Good! The sprite "myproject" is already available. Now let me check if the code already on the sprite and run the tests.
⏺ Bash(sprite exec -s myproject ls -la)
[...]
(it should have omitted -s myproject).
Ugly: Coding agents often assume sprite exec is a shell
⏺ Bash(sprite exec 'cd myproject && git status')
⎿ Error: Exit code 1
executable file `cd myproject && git status` not found in $PATH: No such file or directory
Could exec be interpreted by a shell by default?
Ugly: sprite exec -dir only supports absolute paths
Coding agents often forget the /home/sprite prefix, which fails. Then they fall back to sprite exec sh -c 'cd myproject && …. I wish you could pass a relative directory, eg -dir myproject instead of -dir /home/sprite/myproject.