This article follows the official documentation. We haven’t tested this tool for a hands-on review.
When a coding agent needs a Linux environment apart from the developer’s computer, it can use Fly.io Sprites, a service that provides cloud computers with persistent filesystems. The sprite command-line interface lets you select a Sprite and run commands inside it. An agent can then inspect or work in a remote checkout, the working copy of a repository, while your local files stay separate.
A Sprite keeps files between sessions, but it pauses when it has no active session or HTTP requests. That matters for work that must keep running unattended. The examples below show how to authenticate, select an existing Sprite, and run read-only checks. See Fly.io’s CLI command reference for installation instructions and the full command syntax. These instructions are based on the documentation; the CLI was not installed or tested for this article.
Select a Sprite
First, authenticate with sprite login. The command handles account authentication; keep credentials out of the agent’s prompt. For continuous integration, the CLI also provides sprite auth setup for configuring authentication. Follow the official instructions for the environment where the CLI runs, and provide any required credential through that environment’s secret-handling mechanism.
Once authenticated, list the Sprites available to your account:
sprite list
The command contacts Fly.io and displays available Sprites. Choose one that already contains the checkout the agent should inspect. To make it the default for the current directory, run:
sprite use <sprite-name>
Replace <sprite-name> with the name shown by sprite list. This writes a .sprite file in the current local directory and tells later commands which Sprite to use. Check the file before committing it; it records which remote environment commands target.
Run a read-only inspection
With a Sprite selected, an agent can inspect the remote checkout without changing files:
sprite exec -- pwd
sprite exec -- git status --short
exec runs the command on the selected Sprite. The first command prints the remote working directory. The second asks Git which tracked files have changes and which files Git does not track. Both commands leave the checkout unchanged. The output comes from the remote environment, not the developer’s local shell.
For this example, the Sprite must already contain the repository and have Git available. If either condition is missing, these commands will not inspect the intended project. An agent prompt could be:
In the selected Sprite, report the repository’s current directory and summarize the output of
git status --short. Do not change files or run commands that modify the checkout.
The CLI sends each exec request to Fly.io, which runs the command in the Sprite and returns its output. A command changes the remote filesystem if it writes files or installs packages. Tests with side effects change it too. Review such commands separately before asking an agent to run them.
Understand persistence and pauses
A Sprite’s filesystem persists across sessions, and the CLI supports checkpoints that save filesystem state and restore it later. This lets an operator return to a saved state after changes. The command reference documents checkpoint creation, listing, inspection, deletion, and restoration.
Persistence does not mean a Sprite runs continuously. Fly.io pauses Sprites when they have no HTTP requests and no active sessions. Services configured to run in a Sprite keep it alive and restart when it boots. For a long-running agent task, account for this behavior: when a command ends its session, the command alone does not keep the Sprite active.
Use the CLI for remote shell work
The CLI also includes sprite console for an interactive shell, sprite proxy for forwarding local ports through a Sprite, and sprite url for managing URLs. Those commands support different tasks than the read-only inspection above; consult the command reference before exposing a service or changing a Sprite’s configuration.
For coding agents that need a remote Linux checkout, sprite exec offers a direct way to run shell commands in a selected persistent environment. Start with read-only commands, verify the selected Sprite and repository, then authorize any command that changes remote state. Browse Awesome CLI for other command-line tools used with coding agents.