> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/sprites/integrations/remote-mcp/).

## 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](https://sprites.dev/account) 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](https://github.com/superfly/sprites-codex-plugin) 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:

```sh theme={null}
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:

```text theme={null}
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](https://github.com/superfly/sprites-cursor-plugin) bundles the hosted MCP server and Sprites workflow guidance. Cursor starts browser OAuth on the first Sprites request.

Verify it by asking:

```text theme={null}
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`:

```json theme={null}
{
  "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](https://github.com/superfly/sprites-antigravity-plugin) from GitHub:

```sh theme={null}
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:

```text theme={null}
/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](https://github.com/superfly/sprites-grok-plugin):

```sh theme={null}
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.

<Warning>
  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.
</Warning>

## DeepSeek Harness

The [Sprites bundle for DeepSeek Harness](https://github.com/superfly/sprites-deepseek-plugin) 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:

```sh theme={null}
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:

```sh theme={null}
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](https://github.com/superfly/sprites-opencode-plugin) supports OpenCode 1.18.23 or newer and OpenCode 2 beta.

<Warning>
  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.
</Warning>

```sh theme={null}
git clone https://github.com/superfly/sprites-opencode-plugin.git
```

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

```json theme={null}
{
  "$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:

```sh theme={null}
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](https://github.com/superfly/pi-sprites) requires Node.js 24 or newer. It is not published to npm, so install it directly from GitHub:

```sh theme={null}
pi install git:github.com/superfly/pi-sprites
```

Set the Sprites token in the environment that launches Pi:

```sh theme={null}
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:

```text theme={null}
/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](https://github.com/superfly/herdr-sprites-plugin), listed in the [Herdr plugin marketplace](https://herdr.dev/plugins/), 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:

```sh theme={null}
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:

```json theme={null}
{
  "org": "your-sprites-organization",
  "agent": "claude"
}
```

Choose `claude`, `codex`, or `opencode` for `agent`.

<Warning>
  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](https://github.com/superfly/herdr-sprites-plugin#agent-login-handoff) for supported credential sources and limitations.
</Warning>

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

```sh theme={null}
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:

```sh theme={null}
herdr plugin action invoke info --plugin sprites
```

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

```sh theme={null}
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](https://github.com/superfly/herdr-sprites-plugin#worktree-transfer) for exclusions and size limits.

Stop preserves the Sprite and checkpoints; it does not delete them. See the [plugin actions](https://github.com/superfly/herdr-sprites-plugin#actions) for reconnecting and confirmed cleanup.

## Hermes Agent

The [Sprites plugin for Hermes Agent](https://github.com/NousResearch/hermes-plugin-sprites) 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](https://github.com/NousResearch/hermes-agent) that includes the pluggable terminal-backend extension ([Hermes PR #94400](https://github.com/NousResearch/hermes-agent/pull/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:

```sh theme={null}
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](https://sprites.dev/account) for the intended organization. Edit `~/.hermes/.env` locally and add the token, replacing this placeholder. Keep existing settings in the file:

```dotenv theme={null}
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:

```sh theme={null}
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:

```text theme={null}
Use the terminal tool to run uname -a and pwd.
```

Inspect the actual tool result and confirm the Sprite appears in your [Sprites dashboard](https://sprites.dev/). 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.

<Warning>
  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.
</Warning>

See the [plugin's behavior notes](https://github.com/NousResearch/hermes-plugin-sprites#behavior) 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](/sprites/integrations/cortex-code/).

## If setup gets stuck

* **OAuth fails or repeats:** see [authentication troubleshooting](/sprites/integrations/remote-mcp/#authentication-loops-or-fails).
* **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](/sprites/integrations/remote-mcp/#a-sprite-is-not-found).
* **A package cannot be found:** check the integration's source-installation notice above before trying another package with a similar name.