# The runtime CLI

The CLI drives every Runtime Cloud product from a terminal or a script. It
comes with the JavaScript SDK, needs Node 22 or later, has no dependencies and
starts in about 30 ms. Run it without installing, or install it once:

```bash no-run
npx withruntime run -- python3 -c 'print(6 * 7)'   # without installing
npm install --global withruntime                   # then the command is runtime
runtime run -- python3 -c 'print(6 * 7)'
```

The examples below use `runtime`, the installed command. Without installing,
write `npx withruntime` in its place. Commands read
`runtime <product> <command>`, with account commands at the top. `runtime` on
its own says whether this machine is connected and what to run first.

## One command in a fresh sandbox

```bash
runtime run -- python3 -c 'print(6 * 7)'
runtime run --keep --vcpu 2 -- nproc   # keeps it, and prints how to run more
```

`run` creates a sandbox, runs the command, prints its output, stops the sandbox
and exits with the command's exit code. It takes the same options as
`sandbox create`. `--keep` leaves the sandbox running for more commands.

## Connect once

Any command connects this machine the first time it needs to, so there is no
separate step. To connect ahead of time:

```bash no-run
runtime login                 # opens your browser; approve Connect agent
runtime login --no-browser    # prints a link and a code for another device, and exits
runtime login --wait          # waits for an approval already asked for
runtime login --with-key      # or paste a key from withruntime.com/account/keys
runtime whoami
```

The CLI receives and saves its own credential automatically. You do not copy an
API key. At a terminal, login waits for the approval. Run by an agent (no
terminal), it waits up to 50 seconds, then prints the link and code and exits
with `connection_pending`; `--no-browser` exits at once. The request is saved,
so once it is approved, the same command again, or any other, finishes the
connection with no new link. A request expires after 15 minutes.

`--with-key` reads the key from standard input (piped, or typed without echo),
never from the command line. `RUNTIME_API_KEY` overrides the saved connection
when it is set, which is how CI and scripts run; in CI (the `CI` variable set)
or with `RUNTIME_NO_LOGIN=1`, a missing key is an error instead of a browser
approval.

## Sandboxes

```bash
id=$(runtime sandbox create --name demo --label team=search)
runtime sandbox exec "${id}" -- python3 -c 'print(6 * 7)'
runtime sandbox exec "${id}" --cwd /workspace --env API_TOKEN="${API_TOKEN}" -- env
runtime sandbox ls
runtime sandbox get "${id}"
runtime sandbox stop "${id}"
```

`create` prints only the id, so it composes with `$(...)`, and waits until the
sandbox is running (`--no-wait` returns at once). Its options:
`--vcpu`, `--memory` and `--disk` in MiB, `--timeout <seconds>`,
`--on-timeout pause|stop`, `--trial` or `--paid`, `--name`, `--label k=v`
(repeatable), and network rules: `--no-internet`, `--allow <host>`,
`--deny <host>` and `--connect <host:port>`.

`exec` streams output as it happens and exits with the command's own exit code
(124 when it timed out), so `set -e` scripts behave. Pass secrets with `--env`
from a variable, never written into the command.

Background work, logs and a terminal:

```bash
id=$(runtime sandbox create)
pid=$(runtime sandbox spawn "${id}" -- python3 -m http.server 8000)
runtime sandbox ps "${id}"
runtime sandbox logs "${id}" "${pid}"
runtime sandbox kill "${id}" "${pid}"
runtime sandbox stop "${id}"
```

```bash no-run
runtime sandbox shell "${id}"               # an interactive terminal, like ssh
runtime sandbox logs "${id}" "${pid}" -f      # follow until the process exits
```

Files. Name a sandbox path as `<id>:/path`; directories copy whole:

```bash
id=$(runtime sandbox create)
mkdir -p project && echo "print('hi')" > project/main.py
runtime sandbox cp ./project "${id}:/workspace/project"
runtime sandbox files "${id}" /workspace --depth 2
runtime sandbox cat "${id}" /workspace/project/main.py
runtime sandbox cp "${id}:/workspace/project" ./project-copy
runtime sandbox stop "${id}"
```

Lifecycle: `pause`, `wake`, `restart`, `extend <id> <seconds>`, `stop`.

## Code, previews, network rules and the desktop

```bash no-run
runtime sandbox run-code "${id}" analysis.py --out-dir charts   # a notebook cell; charts saved as PNG
runtime sandbox preview "${id}" 3000 --public                  # an HTTPS address for a port
runtime sandbox previews "${id}"
runtime sandbox unshare "${id}" 3000
runtime sandbox network "${id}"                                # show its rules
runtime sandbox network "${id}" --allow pypi.org --allow '*.pythonhosted.org'
runtime sandbox network "${id}" --no-internet
runtime sandbox desktop "${id}" start                          # prints a link to watch it
runtime sandbox desktop "${id}" open https://example.com
runtime sandbox desktop "${id}" screenshot screen.png
```

A preview's address is under `runtimehost.com`, the domain for everything
sandboxes serve, kept apart from Runtime's own site.

## Images, volumes and snapshots

Forks and snapshots are paused while we fix an issue: for now `fork`, `snapshot`
and a create naming `snapshot` answer 503 `fork_unavailable`. Your sandboxes are
unaffected.

```bash no-run
img=$(runtime image build --pip pandas --apt jq --name data)   # or --dockerfile ./Dockerfile, or --from python:3.12-slim
vol=$(runtime volume create --size-mib 10240 --name cache)
id=$(runtime sandbox create --image "${img}" --volume "${vol}:/data")
base=$(runtime sandbox create --image "${img}")
runtime sandbox fork "${base}" --count 3              # three running copies of it
snap=$(runtime sandbox snapshot "${base}" --name ready)
runtime sandbox create --snapshot "${snap}"           # a copy, any time later
runtime image ls; runtime volume ls; runtime snapshot ls
```

A Dockerfile build sends the files its `COPY` and `ADD` lines name, from the
Dockerfile's folder: at most 256 files and 1 MiB. A volume lives on one server
and is not backed up off it. A fork or snapshot pauses a running sandbox for the moment
it takes, then wakes it; a sandbox with volumes cannot be snapshotted.

## Scripts and agents: `--json`

Every command takes `--json` and prints one JSON value. Errors become
`{"error": {"code", "message", "hint", "requestId"}}` on standard error with a
non-zero exit.

```bash
id=$(runtime sandbox create --trial)
runtime sandbox get "${id}" --json
runtime sandbox exec "${id}" --json -- uname -a
runtime sandbox stop "${id}" --json
```

`runtime sandbox get --json` answers the sandbox as the API does:

```json
{
  "id": "0b8f3c52-6d8e-4b1f-9c67-2f4e6c1d9a10",
  "kind": "sandbox",
  "name": null,
  "labels": {},
  "state": "running",
  "region": "us-east-vin",
  "funding": "trial",
  "vcpu": 2,
  "memoryMiB": 4096,
  "diskMiB": 4096,
  "cpu": "shared",
  "cpuFloorMillis": 50,
  "timeoutSeconds": 1800,
  "onLeaseEnd": "pause"
}
```

## Account

```bash
runtime whoami
runtime usage
runtime ls
```

`runtime limits` says whether this machine's key is read-only and what its
daily spending limit is, with what was used in the last 24 hours and what is
left; it arrived in 0.3.1. Only an account owner sets or changes the limit, at
[API keys](https://withruntime.com/account/keys); see [security](./security).

`runtime ls` lists everything the account runs, every product. `runtime docs
<page>` prints any page of these docs. `runtime mcp` serves Runtime's MCP tools
on stdio for agents that want a local command; see [MCP](./mcp).

When something is broken, missing or confusing, say so; it goes straight to the
people building Runtime:

```bash no-run
runtime feedback "exec output lost its colours" --kind bug
```

```bash no-run
runtime support "my sandbox will not wake"
```

See [feedback and support](./feedback-and-support).

## Sign out

```bash no-run
runtime logout
```

`logout` revokes this machine's connection. It does not stop running sandboxes.