Agent plugins

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:

git clone https://github.com/superfly/sprites-codex-plugin.git
cd sprites-codex-plugin
codex plugin marketplace add .

Restart Codex, open its plugin directory, choose the Sprites marketplace, and install Sprites. Then ask:

List my Sprites.

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:

List my Sprites.

If you only need the MCP tools, you can add the server directly to ~/.cursor/mcp.json or a project’s .cursor/mcp.json:

{
  "mcpServers": {
    "sprites": {
      "url": "https://sprites.dev/mcp"
    }
  }
}

The direct MCP entry does not include the plugin’s bundled workflow guidance.

Antigravity

Install the Sprites plugin for Antigravity from GitHub:

agy plugin install https://github.com/superfly/sprites-antigravity-plugin

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:

/sprites:list

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:

grok plugin install superfly/sprites-grok-plugin --trust
grok plugin enable sprites

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:

npx @deepseek-ai/dsh plugin --profile web add github:superfly/sprites-deepseek-plugin
npx @deepseek-ai/dsh --profile web

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:

npx @deepseek-ai/dsh --profile web --dump-config

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.

Source installation for now

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.

git clone https://github.com/superfly/sprites-opencode-plugin.git

For OpenCode 1, add the absolute package URL to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["file:///absolute/path/to/sprites-opencode-plugin"]
}

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:

opencode mcp auth sprites

Use opencode2 mcp auth sprites for OpenCode 2. No Sprites CLI or pasted API token is required.

Pi

The Pi extension for Sprites requires Node.js 24 or newer. It is not published to npm, so install it directly from GitHub:

pi install git:github.com/superfly/pi-sprites

Set the Sprites token in the environment that launches Pi:

export SPRITES_TOKEN='...'

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:

/sprite list
/sprite new pi-my-project
/sprite-bootstrap

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:

sprite login
herdr plugin install superfly/herdr-sprites-plugin
herdr plugin config-dir sprites

Create config.json in the directory printed by the last command, replacing the organization placeholder:

{
  "org": "your-sprites-organization",
  "agent": "claude"
}

Choose claude, codex, or opencode for agent.

Agent authentication is separate

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.

From a Git worktree in Herdr, launch the configured agent. For a new project, run git init first; no commit is required.

herdr plugin action invoke start-agent --plugin sprites

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:

herdr plugin action invoke info --plugin sprites

To bring remote edits back, stop the agent before pulling:

herdr plugin action invoke stop --plugin sprites
herdr plugin action invoke pull --plugin sprites

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:

git clone https://github.com/NousResearch/hermes-plugin-sprites.git ~/.hermes/plugins/sprites
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python 'sprites-py>=0.5.0,<0.6'

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:

SPRITES_TOKEN=your-sprites-api-token

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 plugins enable sprites
hermes config set terminal.backend sprites
hermes doctor

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:

Use the terminal tool to run uname -a and pwd.

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.

Review what Hermes uploads

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.

See the plugin’s behavior notes for naming, session sharing, and ephemeral mode. Setting 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.