@withruntime/cloud

Runtime Cloud SDK and CLI

One authenticated client for Runtime Cloud. Sandboxes are the first launch product; services, secrets, jobs and notices use the same client and server-side permissions. A method's presence does not enable an unavailable product.

Install with npm install @withruntime/cloud on Node.js 22 or newer.

Set RUNTIME_API_KEY through your server-side secret manager. The default API origin is https://api.withruntime.com; RUNTIME_API_URL can select a test environment. Never put a key in browser code or a command-line argument. For agent setup without copying a key, run npx runtime-cloud login; the CLI and its MCP bridge reuse that private connection.

import { Runtime } from "@withruntime/cloud";

const cloud = new Runtime({
  apiKey: process.env.RUNTIME_API_KEY!,
  baseUrl: process.env.RUNTIME_API_URL,
});
const sandbox = await cloud.sandboxes.create(
  {
    funding: "trial",
    region: "us-east-vin",
    vcpu: 2,
    memoryMiB: 4096,
    diskMiB: 10240,
    durationSeconds: 600,
    cpuMode: "shared",
    cpuFloorMillis: 250,
    memoryGuarantee: "guaranteed",
  },
  { idempotencyKey: "my-job-create-1" },
);
try {
  await cloud.sandboxes.waitUntilRunning(sandbox.id);
  const result = await cloud.sandboxes.exec(
    sandbox.id,
    ["python3", "-c", "print(6 * 7)"],
    {},
    { idempotencyKey: "my-job-exec-1" },
  );
  console.log(result.stdout);
} finally {
  await cloud.sandboxes.stop(sandbox.id, { idempotencyKey: "my-job-stop-1" });
  await cloud.sandboxes.waitUntilStopped(sandbox.id);
}

A create response can be starting; wait before executing. A stop response can be stopping; use get to confirm shutdown. Costs settle after confirmed host shutdown. The simulation field distinguishes a test host from real execution.

Writes use an operation ID. After a lost response, replay identical input with the same ID; a RuntimeError exposes the generated ID as idempotencyKey. The client refuses cross-origin redirects and cleartext remote endpoints.

MCP

Agents supporting Streamable HTTP connect to the approved API origin's /mcp with the bearer key. For clients accepting a local MCP command, run runtime-cloud mcp after installing the reviewed build, with the same environment variables. The bridge discovers remote tools instead of maintaining a second catalogue. It does not run the local Cloud simulator or mint test credit.

The HTTP/SDK/CLI/MCP layers are not separate permissions: the server checks the same organization, key scope, balance and resource ownership for every call.