Metadata-Version: 2.4
Name: runtime-sdk
Version: 0.4.45
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: websockets>=15.0

# runtime-sdk

Python SDK and CLI for Runtime.

## Install

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

The interactive dashboard requires macOS 13+ or 64-bit Linux with glibc 2.17+
or musl 1.2+. On older macOS/Linux environments, the universal wheel keeps
scriptable subcommands available, but bare `runtime` cannot open the OpenTUI
dashboard.

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/runtime --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 ssh <name-or-id>           # open SSH through Runtime's authenticated tunnel
runtime ssh <name-or-id> -- uptime # run a command with the local ssh client
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/runtime
runtime files read <id> /home/runtime/app.py --output app.py
runtime files write <id> /home/runtime/app.py --input app.py --mode 0644
runtime files mkdir <id> /home/runtime/data --parents
runtime files upload <id> ./local-app /home/runtime/app
runtime files download <id> /home/runtime/app ./downloaded-app
runtime files rm <id> /home/runtime/data --recursive
runtime startup show <id>
runtime startup set <id> --command "python3 app.py" --cwd /home/runtime --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 -- python3 app.py
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 -- python3 app.py
#   runtime-env service show
#   runtime-env service clear
```

Private public URLs authenticate the browser before forwarding traffic. Apps
behind a private URL receive trusted `X-Runtime-Account-ID`,
`X-Runtime-User-ID`, and `X-Runtime-User-Email` headers. Runtime strips
client-supplied versions of those headers from both public and private traffic;
public URLs receive no Runtime identity headers.

## 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/runtime",
    port=3000,
)

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

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

# 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> -- <command...>` replaces the durable app command
and starts it. Inside a running computer,
`runtime-env publish <port> -- <command...>` 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.
- New GitHub connects require user authorization during installation and
  `GITHUB_APP_CLIENT_ID` / `GITHUB_APP_CLIENT_SECRET` on the Runtime API.
  In GitHub App settings, enable user authorization during installation and set
  the callback URL to `https://api.runruntime.dev/github/callback`.
- `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/runtime/<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

Set and commit the release version first:

```bash
cd backend
uv version 0.4.45
```

Open the Runtime SDK workflow from that commit, enter the exact committed
version, and run it. The Blacksmith runner tests the Python CLI and OpenTUI,
builds all platform wheels, and publishes them to PyPI.

```bash
gh workflow run runtime-sdk.yml --ref <branch> -f version=0.4.45
```

Preview the runner commands without building:

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

`UV_PUBLISH_TOKEN` is a GitHub repository secret. The release script never
changes the source version and never loads a local `.env` file.
