Metadata-Version: 2.4
Name: runtime-sdk
Version: 0.4.13
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                          # first run in a real terminal prompts for email + verification code, then creates your first computer
runtime login                    # interactive email + verification code flow
runtime login you@example.com
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

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

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

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