# Get started with Runtime Cloud

Runtime Cloud runs your code and your agents' code on machines we operate.
Sandboxes come first: Linux microVMs with their own kernel, disk and toolchain,
usually ready in under a second; startup varies with the workload and capacity.
One API, one CLI, one MCP server and SDKs for
JavaScript and Python cover every Runtime product. New accounts get 20 free
hours with no card: see [the free trial](./trial).

## Run your first sandbox

One line, with Node 22 or later:

```bash
npx withruntime run --trial -- python3 -c 'print(6 * 7)'
```

The first time, it connects this machine: your browser opens a Runtime page
(or the command prints a link and a code), you sign in with Google or an email
link, check the code and choose **Connect agent**. Nothing to copy. Then a fresh
sandbox runs the command, prints 42 and requests a stop. Check the exit code:
zero means the command succeeded. Confirm cleanup with
`npx withruntime sandbox ls --json`; if the test sandbox remains, stop it
and verify its state. The explicit `--trial` refuses paid
funding even if this account has credit. Later commands reuse the connection.

An agent running it shows you the link and code. If you approve after the
command has given up waiting (it waits 50 seconds when no one is at a
terminal), the agent runs it again and it finishes, with no new link.

For several commands in one sandbox, this shell block stops it on exit:

```bash
(
  id=$(npx withruntime sandbox create --trial) || exit
  trap 'npx withruntime sandbox stop "${id}"' EXIT
  npx withruntime sandbox exec "${id}" -- python3 -c 'print(6 * 7)'
)
```

Installed with `npm install --global withruntime`, the command is
`runtime`: `runtime run --trial -- ls`, `runtime sandbox create --trial`. See [the CLI](./cli).

## Give an agent Runtime's tools

Add Runtime's MCP server to your agent with one command:

```bash no-run
claude mcp add --scope user runtime -- npx -y withruntime mcp   # Claude Code
codex mcp add runtime -- npx -y withruntime mcp                 # Codex
```

Cursor: add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{ "mcpServers": { "runtime": { "command": "npx", "args": ["-y", "withruntime", "mcp"] } } }
```

If this machine is not connected yet, the agent sees one tool,
`runtime_connect`, which gives it a link for you to approve; then every Runtime
tool appears. See [MCP](./mcp) for other clients and the remote endpoint.

## From code

```ts
import { Sandbox } from "withruntime";

const sbx = await Sandbox.create({ funding: "trial" });
try {
  const result = await sbx.exec("python3 -c 'print(6 * 7)'", { check: true });
  console.log(result.stdout);
} finally {
  await sbx.stop();
}
```

```python
from withruntime import Sandbox

with Sandbox.create(funding="trial") as sbx:
    print(sbx.exec("python3 -c 'print(6 * 7)'", check=True).stdout)
```

`npm install withruntime` or `pip install withruntime`. The SDKs
use `RUNTIME_API_KEY` when it is set, and otherwise the key this machine saved
when it connected, so after the one line above they need no setup. On a server,
create a key at https://withruntime.com/account/keys and give it as
`RUNTIME_API_KEY` from your secret manager. `create()` needs no arguments and
waits for readiness and raises `start_failed` if it stops before becoming ready.
The examples insist on trial funding, check the command result, and stop even
after an error. Export anything you need before stopping.

## Connect once in your browser

The browser approval gives this machine its own key, encrypted for it alone and
saved outside your project: the CLI receives and saves its own credential
automatically, and you do not copy an API key. Each connection can use
everything the account can, including its prepaid credit, so approve only
connections you started. Browser sign-out does not revoke one;
`npx withruntime logout` or the API keys page does. See [security](./security).

On a machine with no browser, `npx withruntime login --no-browser` prints
the link to open on another device. To use a key you already have instead,
`npx withruntime login --with-key` reads it from standard input, never
from the command line.

Trial requests never fall back to paid credit. Omitting `funding` can use
prepaid credit after the trial is exhausted. Keep `funding: "trial"` for free
use; choose `funding: "paid"` only when you intend to use credit.

## Give your agent one instruction

> Set up Runtime Cloud for this project: read https://withruntime.com/llms.txt,
> run `npx withruntime run --trial -- echo hello`, and when it prints a link, show
> it and the matching code to me and wait for my browser approval. Do not ask
> me for an API key or switch to paid credit. Check the output, exit code and
> cleanup. Report any blocker without exposing credentials or private files.

## If the first run fails

Keep the error code, request ID and sandbox ID. A lost response is not proof
that nothing ran: inspect the original resource before trying another create.
For `connection_pending`, approve the printed request and rerun the same command.
For `trial_busy` or `trial_exhausted`, inspect your trial usage; do not add
`--paid` without deciding to use credit. For `start_failed`, read the sandbox's
state and `stopReason`; never treat a stopped sandbox as ready. See
[troubleshooting](./troubleshooting) for safe retries and cleanup.

## What you can do next

| You want to                                        | Read                                             |
| -------------------------------------------------- | ------------------------------------------------ |
| Run commands, stream output, start servers         | [JavaScript](./javascript) or [Python](./python) |
| Drive sandboxes from a terminal or a script        | [CLI](./cli)                                     |
| Give an agent Runtime tools                        | [MCP](./mcp)                                     |
| Call the API from any language                     | [API reference](./api)                           |
| Know what is installed and what the network allows | [The sandbox environment](./sandbox-environment) |
| Plug into Vercel AI SDK, OpenAI, Claude, LangChain | [Frameworks](./frameworks)                       |
| Move from E2B, Daytona, Vercel or Modal            | [Migration](./migrate)                           |
| Tell us what is missing, or get help               | [Feedback and support](./feedback-and-support)   |

Keep important results outside the sandbox: a sandbox is not a backup.