Get started in 3 minutes

Install the SDK, create a sandbox, run your first command.

Install

$ pip install upstream-sdk

Requires Python 3.10+. The SDK has one dependency: httpx.

Create your first sandbox

from upstream import Upstream

client = Upstream(api_key="sk-...")

with client.sandbox(image="python:3.12") as sb:
    result = sb.exec(["python", "-c", "print('hello from upstream')"])
    print(result.stdout)

This provisions a Firecracker microVM with Python 3.12, executes the command, and tears down the VM when the with block exits.

Claude Code in a sandbox

from upstream import Upstream

client = Upstream(api_key="sk-...")

with client.sandbox(image="claude-code", vcpu=2, memory_mib=2048) as sb:
    result = sb.exec(["claude", "--print", "Write a hello world in Rust"])
    print(result.stdout)

The claude-code template includes Node.js 22, Rust, Python 3, and the Claude Code CLI pre-installed.

Streaming output

with client.sandbox(image="python:3.12") as sb:
    result = sb.exec(["python", "-c", "import time; [print(i) or time.sleep(0.5) for i in range(5)]"], stream=True)
    for line in result.stdout:
        print(line)

File operations

with client.sandbox(image="python:3.12") as sb:
    sb.write_file("/workspace/hello.py", "print('hello')")
    result = sb.exec(["python", "/workspace/hello.py"])
    content = sb.read_file("/workspace/hello.py")

Error handling

from upstream import Upstream, AuthError, QuotaError, SandboxError

try:
    client = Upstream(api_key="sk-...")
    with client.sandbox() as sb:
        sb.exec(["echo", "hello"])
except AuthError:
    print("Invalid API key")
except QuotaError:
    print("Rate limited -- back off")
except SandboxError as e:
    print(f"Sandbox error: {e}")

Next steps