runtime-sdk

Python SDK and CLI for Runtime.

Install

Supported host OS for scriptable CLI commands: Windows, macOS, and Linux.

The interactive dashboard ships in native wheels for Windows ARM64/x64, macOS 13+ ARM64/x64, and 64-bit Linux with glibc 2.17+. Other supported environments receive the universal wheel with the complete scriptable CLI but without the OpenTUI dashboard.

uv tool install runtime-sdk

To upgrade an existing install:

uv tool upgrade runtime-sdk

Configure

The CLI talks to https://api.runruntime.dev by default.

For local or self-hosted Runtime, override it with:

export RUNTIME_BASE_URL=http://127.0.0.1:8080

Or pass --base-url per command.

MCP

ChatGPT and Claude can connect to Runtime at https://api.runruntime.dev/mcp. The connector uses WorkOS OAuth and provisions the same verified-email Runtime account as the CLI. The initial read-only tools are runtime_whoami and runtime_list_computers.

Usage

# Auth
runtime                          # open the interactive dashboard; sign in first if needed
runtime signup                   # enter email, then the six-digit code
runtime login                    # same verified-email flow for new and returning users
runtime login --email me@example.com
printf '%s\n' '123456' | runtime login --email me@example.com --code-stdin
runtime whoami
runtime logout
runtime login --api-key sk_...   # explicit headless credential mode
# Or set RUNTIME_API_KEY for one process without saving it.
runtime api-keys list
runtime api-keys create "my laptop"
runtime api-keys revoke key_01...
runtime integrate github
runtime github list
runtime github disconnect acme

# Computers
runtime switch --repo owner/repo feature/login      # open or create the branch workspace computer
runtime switch -c feature/login --repo owner/repo   # create a new branch workspace from the repo default branch
runtime checkout --repo owner/repo feature/login    # alias for switch
runtime create                       # creates a computer with the starter app already published
runtime create myapp --command "python3 app.py" --cwd /home/runtime --port 3000
runtime create locked --network allowlist --allow-host api.example.com
runtime enter <name-or-id>         # open an interactive shell; accepts slug/name or computer id
runtime enter <name-or-id> -- claude   # open a real TTY and run an interactive command
runtime enter <name-or-id> -- python   # use enter for REPLs, agents, prompts, and full-screen apps
runtime ssh <name-or-id>           # open SSH through Runtime's authenticated tunnel
runtime ssh <name-or-id> -- uptime # run a command with the local ssh client
runtime list                    # print a human-readable computer table
runtime list --json             # one JSON response for scripts and agents
runtime list --json --watch 2   # newline-delimited JSON updates
runtime info <id>
runtime share public <id>
runtime share private <id>
runtime start <id>
runtime run <id> "echo hello"      # one-shot foreground command only
runtime run <id> "apt install -y nodejs" --uid 0
runtime exec <id> -- bash -lc 'for i in 1 2 3; do echo $i; sleep 1; done'
printf 'hello' | runtime exec <id> --stdin -- cat
# runtime run and exec both return the remote exit code; use exec for streamed output and piped stdin.
# Use runtime enter -- <cmd> for interactive TTY commands.
runtime files ls <id> /home/runtime
runtime files read <id> /home/runtime/app.py --output app.py
runtime files write <id> /home/runtime/app.py --input app.py --mode 0644
runtime files mkdir <id> /home/runtime/data --parents
runtime files upload <id> ./local-app /home/runtime/app
runtime files download <id> /home/runtime/app ./downloaded-app
runtime files rm <id> /home/runtime/data --recursive
runtime startup show <id>
runtime startup set <id> --command "python3 app.py" --cwd /home/runtime --port 3000
runtime startup clear <id>          # low-level durable service config
runtime service show <id>           # user-facing alias for the durable published app
runtime service clear <id>
runtime publish <id> 3000 -- python3 app.py
runtime delete <id>

# Network policy
runtime network default show
runtime network default allowlist api.example.com '*.github.com'
runtime network show <id>
runtime network denials <id>
runtime network set <id> none
runtime network set <id> open

# Inside a running computer, the helper installed by Runtime can manage the
# durable app without leaving the sandbox:
#   runtime-env publish 3000 -- python3 app.py
#   runtime-env service show
#   runtime-env service clear

Private public URLs authenticate the browser before forwarding traffic. Apps behind a private URL receive trusted X-Runtime-Account-ID, X-Runtime-User-ID, and X-Runtime-User-Email headers. Runtime strips client-supplied versions of those headers from both public and private traffic; public URLs receive no Runtime identity headers.

Python

from runtime_sdk import RuntimeClient

client = RuntimeClient(base_url="https://api.runruntime.dev", credential="sk_...")

# Or share the CLI's saved API key / WorkOS session and refresh behavior.
client = RuntimeClient.from_config()

# Create a computer. New computers start with the starter app already published.
computer = client.create_computer()
print(computer["public_url"])  # https://goldbird.runruntime.dev

# Or create one with an explicit durable app command.
# That saved service is replayed after cold restore / start.
app = client.create_computer(
    slug="myapp",
    command="python3 app.py",
    cwd="/home/runtime",
    port=3000,
)

# Account defaults are copied only to computers created later.
client.set_default_network("allowlist", ["api.example.com"])
restricted = client.create_computer()
client.set_computer_network(restricted["id"], "none")

# Run a command
result = client.run_command(computer["id"], "echo hello")
print(result["stdout"])

client.write_file(computer["id"], "/home/runtime/hello.txt", b"hello\n")
print(client.read_file(computer["id"], "/home/runtime/hello.txt"))
print(client.list_files(computer["id"], "/home/runtime"))

# Wake a cold computer explicitly
client.start_computer(app["id"])

# Promote the running app on a local port to the durable public app.
# Runtime inspects the listening process and saves its command + cwd when possible.
client.publish_port(computer["id"], 3000)

# List, info, delete
computers = client.list_computers()
info = client.get_computer(computer["id"])
client.delete_computer(computer["id"])

SDK response and stream contracts

The CLI and SDK intentionally have different envelopes:

• CLI control commands are human-readable by default. Add --json for one JSON object with "success": true on stdout. JSON errors use non-zero process status and a JSON object on stderr.
• SDK methods return the API payload directly. They do not add a success field. High-use payloads and exec events are exported as TypedDict types from runtime_sdk.
• File reads return exact bytes. Streaming methods yield events as they arrive; they do not collect them into a control-response envelope.

RuntimeClient is synchronous. stream_command() yields parsed, discriminated ExecEvent objects from NDJSON. Stop iteration by calling close() on the generator (or by using contextlib.closing) to close the HTTP connection immediately. stream_service_logs() yields raw NDJSON lines. There is no async client until a concrete consumer requires one.

Command request timeouts, open stream lifetime, durable service lifetime and computer auto-delete TTL are separate boundaries. The normal client timeout is 10 seconds; lifecycle operations raise it to the 180-second warmup window; open streams have no client deadline and end on server completion, connection failure or caller cancellation.

Pre-1.0 compatibility policy

runtime-sdk supports Python 3.11, 3.12 and 3.13. Before 1.0:

• Patch releases may add optional response fields and event variants. Clients must ignore fields they do not understand.
• Existing method arguments, required fields and scriptable CLI output are not removed or incompatibly changed in a patch release.
• Deprecations are documented and retained through at least the next minor release. A pre-1.0 minor release may contain a documented breaking change.
• A breaking scriptable CLI output change is treated the same as an SDK API break; human-readable help text is not a machine contract.
• Supported Python versions are removed only in a documented minor release.

Development

For fast local backend iteration:

make local-backend

For deploying and testing against the Hetzner production server:

make sync SERVER_IP=x.x.x.x SSH_USER=root
make smoke

Use make deploy instead of make sync when migrations, env files, Caddy, or systemd units changed.

Cold restore and explicit runtime start replay the saved published app command. New computers seed that durable app from the starter workspace. Later, runtime publish <id> <port> -- <command...> replaces the durable app command and starts it. Inside a running computer, runtime-env publish <port> -- <command...> does the same thing using a computer-scoped token installed by Runtime. runtime service show|clear and runtime-env service show|clear expose that same durable app state directly. The low-level runtime startup ... commands still map to the same durable state. A one-off runtime run stays one-shot: the filesystem is restored after going cold, but that ad-hoc process is not.

GitHub branch workspaces

runtime switch gives a repo branch its own Runtime computer so you can jump between parallel tasks without local worktrees.

runtime integrate github
runtime github list
runtime switch --repo owner/repo feature/login
runtime switch -c feature/search --repo owner/repo --from main

Rules:

• GitHub must already be connected with runtime integrate github.
• Run runtime integrate github again when you want to add another personal account or org.
• New GitHub connects require user authorization during installation and GITHUB_APP_CLIENT_ID / GITHUB_APP_CLIENT_SECRET on the Runtime API. In GitHub App settings, enable user authorization during installation and set the callback URL to https://api.runruntime.dev/github/callback.
• runtime switch opens an existing branch workspace, or creates the computer if the branch exists but the workspace does not yet.
• runtime switch -c creates a new branch first, then opens that branch's workspace.
• Each repo + branch maps to one dedicated computer.
• The repo is cloned into /home/runtime/<repo> and new shells in that computer start there automatically.
• runtime checkout ... is an alias for runtime switch ....

Run the SDK unit tests through the backend project environment:

uv run python -m unittest discover -s scripts/tests -p 'test_*.py'

Release

Set and commit the release version first:

cd backend
uv version <next-version>

Merge the release version to main, then run the Runtime SDK workflow with the exact committed version. The workflow tests the Python CLI and OpenTUI, builds all platform wheels, runs the installed Windows wheels against production, and only then publishes those same artifacts to PyPI.

VERSION="$(uv version --short)"
gh workflow run runtime-sdk.yml --ref main -f version="${VERSION}" -f publish=true

Preview the runner commands without building:

./scripts/release_runtime_sdk.sh --dry-run

RUNTIME_WINDOWS_SMOKE_API_KEY is the production smoke credential; UV_PUBLISH_TOKEN is used only by the publish job after every wheel and the Windows production smoke pass. The build script never publishes, changes the source version, or loads a local .env file.