runtime-sdk

Python SDK and CLI for Runtime.

Install

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

The interactive dashboard requires macOS 13+ or 64-bit Linux with glibc 2.17+. On older macOS or musl-based Linux environments, the universal wheel keeps scriptable subcommands available, but bare runtime cannot open the OpenTUI dashboard.

Windows is not supported at this time.

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.

Usage

# Auth
runtime                          # open the interactive dashboard; sign in first if needed
runtime login                    # WorkOS device login; opens the verification page
runtime login --no-open          # print the URL and code for a browserless host
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                    # open the computer dashboard in a terminal
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
# Use runtime exec for automation and exact exit codes; 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_...")

# 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"])

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>

Open the Runtime SDK workflow from that commit, enter the exact committed version, and run it. The Blacksmith runner tests the Python CLI and OpenTUI, builds all platform wheels, and publishes them to PyPI.

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

Preview the runner commands without building:

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

UV_PUBLISH_TOKEN is a GitHub repository secret used only by the publish job after every wheel passes its platform gate. The build script never publishes, changes the source version, or loads a local .env file.