Python SDK

Sync and async clients for the upstream platform. Requires Python 3.10+.

$ pip install upstream-sdk

Upstream (sync client)

The primary entry point. Wraps an httpx.Client for synchronous HTTP.

api_key	str	Your API key (starts with sk-)
base_url	str	API base URL. Override for self-hosted deployments.
timeout	float	HTTP request timeout in seconds.

sandbox()

Create a sandbox session. Returns a Sandbox context manager.

image	str	Template or image name. See Templates.
vcpu	int	Virtual CPU count (1--4).
memory_mib	int	Memory in MiB (128--2048).
ready_timeout	float	Max seconds to wait for VM to become ready.

with client.sandbox(image="python:3.12", vcpu=2, memory_mib=512) as sb:
    result = sb.exec(["python", "-c", "print('hello')"])

run()

Submit a markdown pipeline to the turn executor and poll until complete.

markdown	str	Markdown pipeline content with fenced bash blocks.
poll_interval	float	Seconds between status polls.
timeout	float	Max seconds to wait for completion.

usage()

Get account usage summary.

close()

Close the underlying HTTP client. Called automatically if using context manager patterns.

AsyncUpstream

Async variant. Same interface, backed by httpx.AsyncClient. Use as an async context manager.

from upstream import AsyncUpstream

async with AsyncUpstream(api_key="sk-...") as client:
    usage = await client.usage()

Sandbox

Represents a live Firecracker microVM session. Use as a context manager for automatic cleanup.

exec()

Execute a command inside the sandbox.

command	list[str]	Command and arguments as a list.
stream	bool	If True, returns StreamingExecResult with iterable stdout.

write_file()

Write a file inside the sandbox. Uses exec with a heredoc internally.

read_file()

Read a file from the sandbox. Raises SandboxError if the file does not exist.

destroy()

Destroy the sandbox VM. Called automatically when the with block exits.

Data types

ExecResult

Returned by sb.exec() when stream=False (the default).

Field	Type	Description
exit_code	int	Process exit code (0 = success)
stdout	str	Standard output
stderr	str	Standard error

StreamingExecResult

Returned by sb.exec(stream=True). Iterates stdout lines as they arrive.

Field	Type	Description
stdout	Iterator[str]	Yields lines as they arrive from the VM
exit_code	int	Process exit code (available after iteration)

RunResult

Returned by client.run().

Field	Type	Description
run_id	int	Unique run identifier
status	str	"completed" or "failed"
step_count	int	Total pipeline steps
pass_count	int	Steps that passed
raw	dict	Full JSON response

Usage

Field	Type	Description
total_sessions	int	Total sandbox sessions created
total_vcpu_seconds	float	Total compute consumed
raw	dict	Full JSON response

Exceptions

All exceptions inherit from UpstreamError, which carries an optional status_code.

Exception	HTTP codes	When
AuthError	401, 403	Invalid or missing API key
QuotaError	429	Rate limit or quota exceeded
SandboxError	4xx	Sandbox-specific failures (create, exec, destroy)
TimeoutError	--	Sandbox not ready or exec not complete in time
UpstreamError	5xx	Base class; server errors