cotera
Logo

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 and open your account page, 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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