runtime-sdk 0.4.12

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_...
runtime api-keys list
runtime api-keys create "my laptop"
runtime api-keys revoke 123

# Computers
runtime create                       # creates a computer with the starter app already published
runtime create myapp --command "python3 app.py" --cwd /home/ubuntu --port 3000
runtime enter <name-or-id>         # accepts slug/name like test, or the computer id
runtime list
runtime info <id>
runtime start <id>
runtime run <id> "echo hello"      # one-shot foreground command only
runtime run <id> "apt install -y nodejs" --uid 0
runtime startup show <id>
runtime startup set <id> --command "python3 app.py" --cwd /home/ubuntu --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           # promote the running app on port 3000 to the public durable app
runtime delete <id>

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

Python

from runtime_sdk import RuntimeClient

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

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

# 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> can promote a running listener into the saved public app definition by inspecting the live process. Inside a running computer, runtime-env publish <port> 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.

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.