withruntime 0.2.2 → 0.3.0

package/README.md

@@ -1,7 +1,71 @@
-# withruntime
+# Runtime Cloud SDK and CLI
 
-This name belongs to [Runtime Cloud](https://withruntime.com) and forwards to the official package, [`@withruntime/cloud`](https://www.npmjs.com/package/@withruntime/cloud).
+One client for every Runtime Cloud product, and the `runtime` CLI. No
+dependencies; Node.js 22 or later, or Bun.
 
-```sh
-npx @withruntime/cloud --help
+```bash no-run
+npm install withruntime
 ```
+
+The client uses `RUNTIME_API_KEY` when it is set, and otherwise the connection
+this machine saved when the CLI connected it (one browser approval, no key to
+copy). On a server, set `RUNTIME_API_KEY` from your secret manager (create a key
+at https://withruntime.com/account/keys). Never put a key in browser code, a URL
+or a command-line argument.
+
+```ts
+import { Sandbox } from "withruntime";
+
+await using sbx = await Sandbox.create();
+const result = await sbx.exec("python3 -c 'print(6 * 7)'");
+console.log(result.exitCode, result.stdout);
+```
+
+`Sandbox.create()` needs no arguments and returns once the sandbox is running;
+`await using` stops it when the block ends (Node 24, Bun or TypeScript; on
+Node 22 call `await sbx.stop()`). With no arguments you get the free
+trial while it lasts (20 hours, up to three sandboxes at once), 2 vCPU, 4 GiB of
+memory and a 4 GiB disk.
+
+The sandbox object does the rest:
+
+- `exec`, `execStream`, `spawn` and `processes` for commands and background
+  work, with `cwd`, `env` (the place for secrets), `stdin` and `timeoutMs`;
+- `terminal()` for an interactive terminal over a WebSocket;
+- `files` to read, write, list, glob, stat, move and remove, and to copy whole
+  directories with `upload` and `download`;
+- `pause`, `wake`, `extend`, `fork` and `snapshot`;
+- `interpreter`, `network`, `previews` and `desktop` for the other products.
+
+The client has `sandboxes`, `images`, `volumes`, `snapshots`, `feedback` and
+`support`. Every write carries an idempotency key, made for you, so the SDK's
+own retries (timeouts, 429, 503) never do anything twice. Errors are typed and
+carry a `code`, a `hint` and a `requestId`.
+
+## CLI
+
+```bash no-run
+npx withruntime run -- python3 -c 'print(6 * 7)'   # connects on first use
+npx withruntime sandbox create
+npx withruntime help
+```
+
+Installed with `npm i -g withruntime`, the command is `runtime`:
+`runtime sandbox exec <id> -- ls`, `runtime sandbox shell <id>`,
+`runtime image build --pip pandas`, and `--json` on every command.
+
+## MCP
+
+```bash no-run
+claude mcp add --scope user runtime -- npx -y withruntime mcp
+codex mcp add runtime -- npx -y withruntime mcp
+```
+
+The bridge serves Runtime's MCP tools on stdio over the saved connection; not
+connected yet, it offers `runtime_connect`, which walks you through the browser
+approval. Remote agents use `https://api.withruntime.com/mcp` with a bearer key.
+
+Docs: https://withruntime.com/docs/javascript and https://withruntime.com/docs/cli.
+
+The package was called `@withruntime/cloud` until 0.3.0. That name, and
+`runtime-cloud` and `withruntime-cloud`, still install this one.

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+type Out = {
+    json: boolean;
+    write: (text: string) => void;
+    error: (text: string) => void;
+};
+export declare function run(argv: string[], env?: NodeJS.ProcessEnv, out?: Out): Promise<number>;
+export declare function describeError(error: unknown, json: boolean): string;
+export {};