Agent plugins let an existing coding agent create and operate Sprites without replacing the agent itself. Unless a section says otherwise, the agent stays on your machine and sends remote work to Sprites through the hosted MCP server.
Before you begin
- Install the coding agent you want to use. Check its section below for any version or runtime requirements.
- Have a Fly.io account with access to the intended Sprites organization.
- For OAuth-based plugins, have a browser available for authorization. For Pi and Hermes Agent, create a Sprites API token and use the storage method in their setup instructions.
- For Herdr, authenticate the Sprites CLI and review the agent login handoff described below.
Run plugin installation commands on your local machine, not inside a Sprite. Keep API tokens out of prompts and committed configuration files.
Codex
The Sprites plugin for Codex adds the hosted MCP server and Sprites workflow guidance.
Install Sprites from the Codex plugin marketplace. On first use, follow the plugin’s browser authentication flow, choose the intended Fly.io organization, and review the connector access policy.
For local installation from a checkout of the repository:
Restart Codex, open its plugin directory, choose the Sprites marketplace, and install Sprites. Then ask:
An empty list still confirms that authentication succeeded. Your local Codex workspace and a Sprite’s filesystem remain separate.
Cursor
Install Sprites from the Cursor Marketplace. The Sprites plugin for Cursor bundles the hosted MCP server and Sprites workflow guidance. Cursor starts browser OAuth on the first Sprites request.
Verify it by asking:
If you only need the MCP tools, you can add the server directly to ~/.cursor/mcp.json or a project’s .cursor/mcp.json:
The direct MCP entry does not include the plugin’s bundled workflow guidance.
Antigravity
Install the Sprites plugin for Antigravity from GitHub:
Open /mcp, authenticate the sprites server in your browser, and use restricted connector access unless the workflow intentionally needs organization-wide control. Verify the connection with:
The plugin also provides commands for creating Sprites, running commands, managing checkpoints and services, and cleaning up environments.
Grok Build
Install and enable the Sprites plugin for Grok Build:
Reload plugins with /plugins and r, or restart Grok. Then run /sprites-status or ask Grok to list your Sprites and complete browser OAuth.
An empty Sprite list means the connection is authenticated. For a fuller check, run /sprites-smoke; it lists Sprites, creates a test Sprite, runs a command, and asks before destroying it.
The --trust flag lets the plugin start its MCP connection. Review the repository before installing it, and prefer the restricted OAuth policy unless Grok needs access to every Sprite in the organization.
DeepSeek Harness
The Sprites bundle for DeepSeek Harness requires Node.js 20.19 or newer and the DeepSeek Harness developer preview.
Install the bundle into the built-in Web profile, then start that profile:
Complete browser OAuth on the first connection. If the initial tool synchronization times out while you authorize, finish the browser flow and restart Harness once.
Verify the installed composition:
The output should include dsh-sprites-plugin, sprites-mcp, and sprites-skill-filesystem. The bundle uses mcp-remote because Harness’s current remote HTTP transport does not complete MCP OAuth itself; you do not need a Sprites API token.
Then ask Harness to list your Sprites and check that the tool returns successfully. The configuration dump confirms installation; it does not by itself confirm an authenticated connection.
OpenCode
The Sprites plugin for OpenCode supports OpenCode 1.18.23 or newer and OpenCode 2 beta.
The package @flydotio/sprites-opencode-plugin is not currently published to npm. Clone the repository and use the checkout path instead of the package name until it is published.
opencode.json:
OpenCode 2 uses the plugins key and accepts either a path or a file:// URL. Restart OpenCode after changing the configuration.
Run /sprites-status or ask OpenCode to list your Sprites. If the browser does not open, start authorization explicitly:
Use opencode2 mcp auth sprites for OpenCode 2. No Sprites CLI or pasted API token is required.
The Pi extension for Sprites requires Node.js 24 or newer. It is not published to npm, so install it directly from GitHub:
Set the Sprites token in the environment that launches Pi:
SPRITE_TOKEN is also accepted. The token stays in the local Pi process and is not copied into remote commands or the Sprite.
Select or create a Sprite, then bootstrap the workspace:
While a Sprite is selected, Pi’s normal file and shell tools operate in the remote workspace. Use /sprite-local to return them to your local machine.
Herdr
The Sprites plugin for Herdr, listed in the Herdr plugin marketplace, runs a coding agent inside a persistent Sprite controlled from a local Herdr pane. Each agent pane gets its own Sprite. Unlike the hosted-MCP plugins above, the agent itself runs remotely.
On your local machine, install Herdr 0.9.0 or newer, Node.js 22 or newer, Git, and the Sprites CLI. The CLI must support exec --tty, sessions, checkpoint create, restore, and api.
Authenticate and install the plugin; no npm install or build step is required:
Create config.json in the directory printed by the last command, replacing the organization placeholder:
Choose claude, codex, or opencode for agent.
By default, the plugin hands off an available local Claude or Codex login to the Sprite. Those credentials remain in the Sprite and its checkpoints and use your provider account. To sign in manually instead, add "auth": "none" to config.json before creating a Sprite. This does not revoke credentials already transferred. OpenCode requires manual authentication. See agent login handoff for supported credential sources and limitations. git init first; no commit is required.
The new split pane shows setup progress followed by the agent terminal. Sign in there if needed. A setup-launched response only means setup started; check the pane and run Info to confirm the Sprite mapping and remote session, or see setup errors:
To bring remote edits back, stop the agent before pulling:
The initial upload includes eligible uncommitted worktree files but excludes local Git history, ignored files, and common credential files. Review source files for embedded secrets before uploading. Changes are not automatically synchronized: Pull refuses overlapping local edits, and Reconnect does not upload new local changes. See worktree transfer for exclusions and size limits.
Stop preserves the Sprite and checkpoints; it does not delete them. See the plugin actions for reconnecting and confirmed cleanup.
Hermes Agent
The Sprites plugin for Hermes Agent adds a terminal backend. Hermes stays on its existing host, while its shell commands execute in persistent Sprites. It uses the Sprites Python SDK and an API token, not hosted MCP or browser OAuth.
Use a current Hermes installation that includes the pluggable terminal-backend extension (Hermes PR #94400). The commands below assume the standard macOS/Linux installation and default ~/.hermes home. For a custom installation or profile, use its plugin directory, secrets file, and Python environment.
Clone the plugin and install its supported SDK version into Hermes’s Python environment, not your system Python:
Create a Sprites API token for the intended organization. Edit ~/.hermes/.env locally and add the token, replacing this placeholder. Keep existing settings in the file:
Do not paste the token into an agent prompt, a shell command saved in history, or a committed file. Enable the plugin and select its backend:
hermes doctor checks whether the token and SDK are present. It does not prove that the token can authenticate to Sprites. Restart any running Hermes session or gateway, then start a new session and ask:
Inspect the actual tool result and confirm the Sprite appears in your Sprites dashboard. The first terminal call creates or resumes a Sprite and can incur usage charges. If the backend is unavailable, check plugin loading, the Hermes version, and whether the SDK was installed in the Python environment Hermes actually uses. For an authorization failure, check the token and organization access.
Sprites persist by default. Gateway and WebUI sessions get separate Sprites; CLI and cron flows without a session key share the profile-default Sprite. Remote edits are not automatically copied back to the host. Bring project files into the Sprite explicitly rather than assuming your local working directory is mirrored.
The backend uses Hermes’s file-sync mechanism to upload configured credential files, skills, and caches. Review that configuration before use: these files can remain in the persistent Sprite and its checkpoints. This upload is separate from syncing your project or copying remote edits back to your machine.
terminal.container_persistent to false creates disposable Sprites that are deleted on cleanup, so do not use that mode for work you need to retain.
Cortex Code
Cortex Code has a focused guide because its plugin includes Snowflake-specific workflows, long-running task support, and explicit authorization steps. Continue with Cortex Code.
If setup gets stuck
- OAuth fails or repeats: see authentication troubleshooting.
- An expected Sprite is missing: check the selected organization and connector access policy. A successful empty list is different from an authentication error; see Sprite visibility.
- A package cannot be found: check the integration’s source-installation notice above before trying another package with a similar name.
