# Sprites

> Provision and control Sprites (sprites.dev) — persistent, hardware-isolated Linux sandboxes with a full filesystem that survives between runs. Create, list, get, and destroy sprites, and run commands inside them.

Source: https://cotera.co/docs/reference/tools/individual-tools/sprites

---

**Authentication Type:** API Key
**Description:** Provision and control Sprites (sprites.dev) — persistent, hardware-isolated Linux sandboxes with a full filesystem that survives between runs. Create, list, get, and destroy sprites, and run commands inside them.

***

## Authentication

To authenticate with Sprites, you'll need a Sprites API token:

1. Sign in at [sprites.dev](https://sprites.dev) and open your [account page](https://sprites.dev/account), or install the CLI and run `sprite org auth`.
2. Create a token. It has the form `org-slug/org-id/token-id/token-value`.
3. Copy the full token value.

You'll need to provide:

* **apiToken** `string`: Your Sprites API token. Tokens grant full control over the organization's sprites, so treat them as secrets.

> **Tip:** Sprites come with common languages (Node.js, Python, Go, Bun, Deno, and more) and the Claude CLI pre-installed, so you can run `claude -p "..."` inside a sprite without building a custom image.

***

## Sprites

### Create Sprite

Create a new sprite: a persistent, hardware-isolated Linux sandbox. The filesystem survives between runs, and the sprite hibernates when idle and wakes on demand.

**Operation Type:** Mutation (Write)

**Parameters:**

* **name** `string` (required): A unique name for the sprite within your organization (e.g., `claude-session-123`). Used to reference the sprite in other operations.
* **urlAuth** `string` (default: `sprite`): Access control for the sprite's HTTP URL — `sprite` (org members only) or `public` (anyone with the URL)
* **waitForCapacity** `boolean` (default: false): When `true`, wait for capacity instead of failing immediately if the platform is at capacity

**Returns:**

* **id** `string`: The sprite's unique ID
* **name** `string`: The sprite name
* **organization** `string`: The organization that owns the sprite
* **url** `string`: The sprite's unique HTTP URL for exposing web services
* **status** `string`: Lifecycle status (`running`/`active`, `warm`, or `cold`)
* **createdAt** `string` (nullable): ISO 8601 creation timestamp
* **updatedAt** `string` (nullable): ISO 8601 last-update timestamp

**Example Usage:**

```json
{
  "name": "claude-session-123",
  "urlAuth": "sprite",
  "waitForCapacity": false
}
```

***

### List Sprites

List the sprites in your organization, optionally filtered by name prefix, with pagination. Use this to discover sprite names before running commands.

**Operation Type:** Query (Read)

**Parameters:**

* **prefix** `string` (nullable): Optional name prefix to filter by (e.g., `dev-`)
* **maxResults** `number` (default: 50): Maximum number of sprites to return (1–50)
* **continuationToken** `string` (nullable): Pagination token from a previous response's `nextContinuationToken`

**Returns:**

* **sprites** `array of objects`: The sprites in this page
  * **name** `string`: The sprite name
  * **orgSlug** `string`: The organization slug that owns the sprite
  * **updatedAt** `string` (nullable): ISO 8601 timestamp of the last update
* **hasMore** `boolean`: `true` when more results are available beyond this page
* **nextContinuationToken** `string` (nullable): Pass as `continuationToken` to fetch the next page, or `null` if none

**Example Usage:**

```json
{
  "prefix": "claude-",
  "maxResults": 50
}
```

***

### Get Sprite

Get a sprite's current status (`running` / `warm` / `cold`), URL, and details by name. Useful for checking whether a sprite exists and its state before running commands.

**Operation Type:** Query (Read)

**Parameters:**

* **name** `string` (required): The name of the sprite to inspect

**Returns:**

* **id** `string`: The sprite's unique ID
* **name** `string`: The sprite name
* **organization** `string`: The organization that owns the sprite
* **url** `string`: The sprite's HTTP URL
* **status** `string`: Lifecycle status (`running`/`active`, `warm`, or `cold`)
* **createdAt** `string` (nullable): ISO 8601 creation timestamp
* **updatedAt** `string` (nullable): ISO 8601 last-update timestamp

**Example Usage:**

```json
{
  "name": "claude-session-123"
}
```

***

### Destroy Sprite

Permanently destroy a sprite by name. This is irreversible and deletes the sprite along with its persistent filesystem.

**Operation Type:** Mutation (Write)

**Parameters:**

* **name** `string` (required): The name of the sprite to destroy

**Returns:**

* **name** `string`: The name of the destroyed sprite
* **destroyed** `boolean`: `true` when the sprite was destroyed

**Example Usage:**

```json
{
  "name": "claude-session-123"
}
```

***

### Run Command

Run a command synchronously inside a sprite and return its output. The call blocks until the command finishes, and the sprite wakes automatically if it was hibernating. Use this to drive the pre-installed Claude CLI or run any other command.

**Operation Type:** Mutation (Write)

**Parameters:**

* **name** `string` (required): The name of the sprite to run the command in
* **command** `array of strings` (required): The command to run as an argv array (e.g., `["claude", "-p", "Summarize the README", "--dangerously-skip-permissions"]`). The first element is the executable. For a shell pipeline, use `["bash", "-c", "your | pipeline"]`
* **dir** `string` (nullable): Optional working directory to run the command in (e.g., `/home/sprite/project`)
* **env** `object` (nullable): Optional environment variables as key-value pairs (e.g., `{"ANTHROPIC_API_KEY": "sk-..."}`)

**Returns:**

* **output** `string`: The command output (combined stdout/stderr) as returned by the sprite
* **exitCode** `number`: The command exit code (0 means success)

**Example Usage:**

```json
{
  "name": "claude-session-123",
  "command": [
    "claude",
    "-p",
    "Summarize the README",
    "--dangerously-skip-permissions",
    "--output-format",
    "json"
  ],
  "dir": "/home/sprite/project"
}
```

***

## Common Use Cases

**Remote Agents & Claude Code:**

* Run the pre-installed Claude CLI inside a sprite and chat with it turn-by-turn via Run Command
* Give an agent a persistent workspace whose files and installed packages survive between runs
* Resume a hibernated sprite to continue a session exactly where it left off

**Ephemeral Compute & Sandboxes:**

* Spin up a sprite, run a task, and destroy it when finished
* Isolate untrusted or AI-generated code in a hardware-isolated environment
* Let sprites hibernate when idle to avoid paying for compute you're not using

**Persistent Dev Environments:**

* Create a long-lived sprite per project with its own filesystem and tooling
* Install dependencies once and reuse them across many command runs
* Expose a service on the sprite's built-in HTTP URL

**Fleet Management:**

* List and inspect sprites across your organization to track their state
* Look up a sprite's status and URL before sending it work
* Tear down environments by destroying their sprites