Metadata-Version: 2.4
Name: runtime-sdk
Version: 0.5.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
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
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: **Windows, macOS, and Linux**.

The interactive dashboard ships in native wheels for Windows ARM64/x64,
macOS 13+ ARM64/x64, and 64-bit Linux with glibc 2.17+. Other supported
environments receive the universal wheel with the complete scriptable CLI but
without the OpenTUI dashboard.

```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                          # open the interactive dashboard; sign in first if needed
runtime signup                   # open WorkOS, then choose Sign up to create an account
runtime login                    # sign in through the WorkOS verification page
runtime login --no-open          # print the URL and code for a browserless host
runtime whoami
runtime logout
runtime login --api-key sk_...   # explicit headless credential mode
# Or set RUNTIME_API_KEY for one process without saving it.
runtime api-keys list
runtime api-keys create "my laptop"
runtime api-keys revoke key_01...
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 create locked --network allowlist --allow-host api.example.com
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                    # print a human-readable computer table
runtime list --json             # one JSON response for scripts and agents
runtime list --json --watch 2   # newline-delimited JSON updates
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
# runtime run and exec both return the remote exit code; use exec for streamed output and piped stdin.
# 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>

# Network policy
runtime network default show
runtime network default allowlist api.example.com '*.github.com'
runtime network show <id>
runtime network denials <id>
runtime network set <id> none
runtime network set <id> open

# 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", credential="sk_...")

# Or share the CLI's saved API key / WorkOS session and refresh behavior.
client = RuntimeClient.from_config()

# 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,
)

# Account defaults are copied only to computers created later.
client.set_default_network("allowlist", ["api.example.com"])
restricted = client.create_computer()
client.set_computer_network(restricted["id"], "none")

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

### SDK response and stream contracts

The CLI and SDK intentionally have different envelopes:

- CLI control commands are human-readable by default. Add `--json` for one JSON
  object with `"success": true` on stdout. JSON errors use non-zero process
  status and a JSON object on stderr.
- SDK methods return the API payload directly. They do not add a `success`
  field. High-use payloads and exec events are exported as `TypedDict` types
  from `runtime_sdk`.
- File reads return exact `bytes`. Streaming methods yield events as they
  arrive; they do not collect them into a control-response envelope.

`RuntimeClient` is synchronous. `stream_command()` yields parsed,
discriminated `ExecEvent` objects from NDJSON. Stop iteration by calling
`close()` on the generator (or by using `contextlib.closing`) to close the HTTP
connection immediately. `stream_service_logs()` yields raw NDJSON lines. There
is no async client until a concrete consumer requires one.

Command request timeouts, open stream lifetime, durable service lifetime and
computer auto-delete TTL are separate boundaries. The normal client timeout is
10 seconds; lifecycle operations raise it to the 180-second warmup window;
open streams have no client deadline and end on server completion, connection
failure or caller cancellation.

### Pre-1.0 compatibility policy

`runtime-sdk` supports Python 3.11, 3.12 and 3.13. Before 1.0:

- Patch releases may add optional response fields and event variants. Clients
  must ignore fields they do not understand.
- Existing method arguments, required fields and scriptable CLI output are not
  removed or incompatibly changed in a patch release.
- Deprecations are documented and retained through at least the next minor
  release. A pre-1.0 minor release may contain a documented breaking change.
- A breaking scriptable CLI output change is treated the same as an SDK API
  break; human-readable help text is not a machine contract.
- Supported Python versions are removed only in a documented minor release.

## 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 discover -s scripts/tests -p 'test_*.py'
```

## Release

Set and commit the release version first:

```bash
cd backend
uv version <next-version>
```

Merge the release version to `main`, then run the Runtime SDK workflow with the
exact committed version. The workflow tests the Python CLI and OpenTUI, builds
all platform wheels, runs the installed Windows wheels against production, and
only then publishes those same artifacts to PyPI.

```bash
VERSION="$(uv version --short)"
gh workflow run runtime-sdk.yml --ref main -f version="${VERSION}" -f publish=true
```

Preview the runner commands without building:

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

`RUNTIME_WINDOWS_SMOKE_API_KEY` is the production smoke credential;
`UV_PUBLISH_TOKEN` is used only by the publish job after every wheel and the
Windows production smoke pass. The build script never publishes, changes the
source version, or loads a local `.env` file.
