Metadata-Version: 2.4
Name: runtime-sdk
Version: 0.4.0
Summary: Runtime Python SDK and CLI
Project-URL: Repository, https://github.com/The-Money-Company-Limited/runtimevm
Project-URL: Issues, https://github.com/The-Money-Company-Limited/runtimevm/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Environment :: Console
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.28.1
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.7
Requires-Dist: websockets>=15.0

# runtime-sdk

Python SDK and CLI for Runtime.

## Install

```bash
uv tool install runtime-sdk
```

To upgrade an existing install:

```bash
uv tool upgrade runtime-sdk
```

## Configure

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

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

Or pass `--base-url` per command.

## Usage

```bash
# Auth
runtime login you@example.com
runtime verify 123456
runtime whoami
runtime logout
runtime login --api-key rt_live_...

# Computers
runtime create                       # in a real TTY, creates then drops you into the console
runtime create myapp --command "python3 app.py" --cwd /home/ubuntu --port 3000
runtime enter <id>                  # enter a fresh console session on an existing computer
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

```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:

```bash
make local-backend
```

For deploying and testing against the Hetzner production server:

```bash
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:

```bash
uv run python -m unittest scripts.tests.test_runtime_sdk
```

## Release

Preview the next release without changing files:

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

Publish a patch release:

```bash
./scripts/release_runtime_sdk.sh --publish
```

Publish a different version bump:

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

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