Sprites Python SDK

Python SDK for Sprites, providing sprite management, remote command execution, filesystem access, checkpoints, services, and network policy controls.

Installation

pip install sprites-py

Quick Start

import os

from sprites import SpritesClient

client = SpritesClient(token=os.environ["SPRITE_TOKEN"])
sprite = client.create_sprite(os.environ["SPRITE_NAME"])

# Run a command
result = sprite.run("echo", "hello", capture_output=True)
print(result.stdout.decode())  # "hello\n"

# Or use the Go-style API
cmd = sprite.command("ls", "-la")
output = cmd.output()
print(output.decode())

sprite.destroy()

API Overview

Async API

Async applications can use the matching native asyncio client. Its network operations use httpx.AsyncClient, and command execution runs directly on the caller's event loop.

from sprites import AsyncSpritesClient

async with AsyncSpritesClient(token="your-token") as client:
    sprite = await client.create_sprite("my-sprite")

    output = await sprite.command("echo", "hello").output()
    result = await sprite.run("uname", "-a", capture_output=True)

    config = sprite.filesystem("/app") / "config.json"
    await config.write_text('{"debug": true}')
    print(await config.read_text())

    async for path in (sprite.filesystem("/app") / ".").iterdir():
        print(path.name)

    await sprite.destroy()

AsyncSpritesClient deliberately returns distinct AsyncSprite, AsyncCmd, and AsyncSpritePath objects. This keeps every I/O method predictably awaitable while preserving the existing synchronous API unchanged.

SpritesClient

from sprites import ListOptions, SpritesClient, URLSettings

client = SpritesClient(
    token="your-token",
    base_url="https://api.sprites.dev",  # optional
    timeout=30.0,  # optional
    control_mode=False,  # optional multiplexed exec transport
)

# Create a sprite
sprite = client.create_sprite(
    "my-sprite",
    url_settings=URLSettings(auth="sprite", private_access="admins"),
    labels=["dev"],
    wait_for_capacity=True,
    runtime="dev",
)

# Get a sprite handle (doesn't create it)
sprite = client.sprite("my-sprite")

# Get a sprite with populated metadata
sprite = client.get_sprite("my-sprite")

# List sprites
page = client.list_sprites(ListOptions(prefix="my-", bulk_load=True))
for item in page.sprites:
    print(item.name, item.status, item.labels)

# Update URL settings and labels
updated = client.update_sprite(
    "my-sprite",
    url_settings=URLSettings(auth="public"),
    labels=["dev", "public-demo"],
)

# Omitted mutable fields are left unchanged by the API.
client.update_sprite("my-sprite", labels=["dev"])

# Destroy a sprite
client.destroy_sprite("my-sprite")

URLSettings.auth is "sprite" or "public". When auth="sprite", private_access may be "admins" or "org_users". update_url_settings(...) is kept as a compatibility convenience for updating only URL settings; prefer update_sprite(...) when changing mutable sprite fields.

Sprite

# Run a command (subprocess.run style)
result = sprite.run("echo", "hello", capture_output=True, timeout=30)
print(result.returncode)
print(result.stdout)

# Create a command (Go exec.Cmd style)
cmd = sprite.command("bash", "-c", "echo hello")
output = cmd.output()  # Returns stdout
combined = cmd.combined_output()  # Returns stdout + stderr

# TTY mode
cmd = sprite.command("bash", tty=True, tty_rows=24, tty_cols=80)
cmd.run()

# Attach to an existing session
sessions = sprite.list_sessions()
cmd = sprite.attach_session(sessions[0].id, timeout=2)
cmd.run()

Commands use WebSockets. If control_mode=True is passed to SpritesClient, new commands use the multiplexed control connection when the sprite supports it and fall back to the standard exec WebSocket otherwise. Use sprite.command(...) instead of sprite.run(...) when you need streaming stdin/stdout/stderr handles.

Filesystem

fs = sprite.filesystem("/app")

(fs / "config.json").write_text('{"debug": true}')
print((fs / "config.json").read_text())

for path in (fs / ".").iterdir():
    print(path.name)

Checkpoints

# List checkpoints
checkpoints = sprite.list_checkpoints()

# Create a checkpoint (five-minute network inactivity timeout by default)
stream = sprite.create_checkpoint("my checkpoint")
for msg in stream:
    print(msg.type, msg.data)

# Restore a checkpoint with a caller-selected timeout
stream = sprite.restore_checkpoint("checkpoint-id", timeout=600)
for msg in stream:
    print(msg.type, msg.data)

Services

# Create or update a service and stream startup events
stream = sprite.create_service(
    "web",
    cmd="python",
    args=["-m", "http.server", "8000"],
    http_port=8000,
    env={"APP_ENV": "production"},
    dir="/app",
)
for event in stream:
    print(event.type, event.data)

# Inspect and control services
services = sprite.list_services()
web = sprite.get_service("web")
sprite.stop_service("web")
sprite.start_service("web")

Network Policy

from sprites import NetworkPolicy, PolicyRule

# Get current policy
policy = sprite.get_network_policy()

# Update policy
new_policy = NetworkPolicy(rules=[
    PolicyRule(domain="example.com", action="allow"),
])
sprite.update_network_policy(new_policy)

Client signals

Requests carry coarse, privacy-safe client signals (Fly-Client-* headers + a User-Agent suffix) so Fly.io can estimate how much API traffic is human- vs. agent-driven. They're advisory only — never used for gating or rate-limiting.

To opt out, set SPRITES_CLIENT_SIGNALS=0 (also accepts off/false/no). When disabled, requests still send a plain sprites-py/<version> User-Agent and no Fly-Client-* headers — the SDK is otherwise unaffected.

Integrations

Framework-specific adapters are published separately so this SDK can remain generic. The OpenAI Agents integration provides a Sprites-backed implementation of the Agents SDK sandbox interface.

Requirements

• Python 3.9+
• websockets
• httpx
• client-signals

License

MIT