runtime-sdk 0.3.0

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 create myapp --command "python3 app.py" --cwd /home/ubuntu --port 3000
runtime list
runtime info <id>
runtime start <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

# Or create one with a durable startup command.
# That startup config is replayed after cold restore / auto-wake.
app = client.create_computer(
    slug="myapp",
    command="python3 app.py",
    cwd="/home/ubuntu",
    port=3000,
)

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

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

# 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.

Cold restore and public auto-wake replay the saved startup command only for computers created with --command + --port (or the SDK command/port arguments). If you start an app later via a one-off runtime run, the filesystem is restored after going cold, but that ad-hoc process is not.

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.