Metadata-Version: 2.4
Name: runtime-sdk
Version: 0.4.38
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
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
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

Supported host OS for the CLI: **macOS and Linux only**.

Windows is **not supported** at this time.

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

To upgrade an existing install:

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

## Configure

The CLI talks to `https://api.runruntime.dev` by default.

For local or self-hosted Runtime, override it with:

```bash
export RUNTIME_BASE_URL=http://127.0.0.1:8080
```

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
runtime integrate github
runtime github list
runtime github disconnect acme

# Computers
runtime switch --repo owner/repo feature/login      # open or create the branch workspace computer
runtime switch -c feature/login --repo owner/repo   # create a new branch workspace from the repo default branch
runtime checkout --repo owner/repo feature/login    # alias for switch
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>         # open an interactive shell; accepts slug/name or computer id
runtime enter <name-or-id> -- claude   # open a real TTY and run an interactive command
runtime enter <name-or-id> -- python   # use enter for REPLs, agents, prompts, and full-screen apps
runtime list
runtime info <id>
runtime share public <id>
runtime share private <id>
runtime start <id>
runtime run <id> "echo hello"      # one-shot foreground command only
runtime run <id> "apt install -y nodejs" --uid 0
runtime exec <id> -- bash -lc 'for i in 1 2 3; do echo $i; sleep 1; done'
printf 'hello' | runtime exec <id> --stdin -- cat
# Use runtime exec for automation and exact exit codes; use runtime enter -- <cmd> for interactive TTY commands.
runtime files ls <id> /home/ubuntu
runtime files read <id> /home/ubuntu/app.py --output app.py
runtime files write <id> /home/ubuntu/app.py --input app.py --mode 0644
runtime files mkdir <id> /home/ubuntu/data --parents
runtime files upload <id> ./local-app /home/ubuntu/app
runtime files download <id> /home/ubuntu/app ./downloaded-app
runtime files rm <id> /home/ubuntu/data --recursive
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"])

client.write_file(computer["id"], "/home/ubuntu/hello.txt", b"hello\n")
print(client.read_file(computer["id"], "/home/ubuntu/hello.txt"))
print(client.list_files(computer["id"], "/home/ubuntu"))

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

## GitHub branch workspaces

`runtime switch` gives a repo branch its own Runtime computer so you can jump
between parallel tasks without local worktrees.

```bash
runtime integrate github
runtime github list
runtime switch --repo owner/repo feature/login
runtime switch -c feature/search --repo owner/repo --from main
```

Rules:
- GitHub must already be connected with `runtime integrate github`.
- Run `runtime integrate github` again when you want to add another personal account or org.
- `runtime switch` opens an existing branch workspace, or creates the computer if
  the branch exists but the workspace does not yet.
- `runtime switch -c` creates a new branch first, then opens that branch's
  workspace.
- Each `repo + branch` maps to one dedicated computer.
- The repo is cloned into `/home/ubuntu/<repo>` and new shells in that computer
  start there automatically.
- `runtime checkout ...` is an alias for `runtime switch ...`.

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.
