runtime-sdk 0.2.1

Runtime Python SDK and CLI

runtime-sdk

Python SDK and CLI for Runtime.

Install

uv tool install runtime-sdk

To upgrade an existing install:

uv tool upgrade runtime-sdk

Configure

The CLI talks to http://127.0.0.1:8080 by default. Override it with:

export RUNTIME_BASE_URL=https://api.runruntime.dev

Or pass --base-url per command.

Usage

# Auth
runtime login [e-mail]
runtime verify 123456
runtime whoami
runtime logout
runtime login --api-key rt_live_...

# Computers
runtime create
runtime list
runtime info <id>
runtime run <id> "echo hello"
runtime run <id> "apt install -y nodejs" --uid 0
runtime publish <id> 3000
runtime delete <id>

Python

from runtime_sdk import RuntimeClient

client = RuntimeClient(base_url="https://api.runruntime.dev", api_key="rt_live_...")

# Create a computer
computer = client.create_computer()
print(computer["public_url"])  # https://goldbird.runruntime.dev

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

# Pin the public URL to a local app port
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.

Run the SDK unit tests through the backend project environment:

uv run python -m unittest scripts.tests.test_runtime_sdk

Release

Preview the next release without changing files:

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

Publish a patch release:

./scripts/release_runtime_sdk.sh --publish

Publish a different version bump:

./scripts/release_runtime_sdk.sh --bump minor --publish

The script loads backend/.env automatically, so UV_PUBLISH_TOKEN can live there.