Run a sandbox

For CLI setup and authentication, see CLI Quickstart.

Create a sandbox

runcloud sandbox create --json

import { Client } from "@run-cloud/sdk";

const cloud = new Client();
const sandbox = await cloud.sandboxes.create({ image: "runcloud/agent-base" });

console.log(sandbox.id, sandbox.state);

With nothing specified you get the default reservation of 0.125 vCPU / 128 MiB. Use exact resources when you need a different allocation:

runcloud sandbox create --cpu 2 --memory 4096 --json

await cloud.sandboxes.create({ cpu: 2, memory: 4096 });

The response includes:

Field	Use
`id`	Sandbox id. Use it with `exec`, `get`, `snapshot`, and `destroy`.
`state`	`running`, `paused`, `stopped`, `interrupted`, or `destroyed`.
`image`	Base image the sandbox booted from.
`milli_cpu`	Reserved CPU in millicores — `125` is the 0.125 vCPU default.
`mem_mb`	Reserved memory in MiB. This is a hard ceiling.
`region`	Where the sandbox was placed.
`created_at`	Creation timestamp.

The TypeScript SDK adds camelCase aliases (milliCpu, memMb, createdAt) alongside the raw API fields, so either spelling works.

Run a command

runcloud sandbox exec sbx_abc123 "npm install && npm test"

const result = await cloud.sandboxes.exec(
  sandbox.id,
  "npm install && npm test",
);

console.log(result.exitCode);
console.log(result.stdout);
console.log(result.stderr);

A string command runs through /bin/sh -c, so pipes and && work. Pass an array instead to execute a program directly without a shell:

await cloud.sandboxes.exec(sandbox.id, ["node", "-e", "console.log(1)"]);

A non-zero exit code is returned, not thrown. Check exitCode yourself; only transport and API failures raise RunCloudError. Exec requires the sandbox to be running; a paused sandbox returns 409.

List and inspect

runcloud sandbox list --json
runcloud sandbox list --state running --json
runcloud sandbox list --name checkout-api --json
runcloud sandbox logs sbx_abc123 --lines 200

const all = await cloud.sandboxes.list();
const running = await cloud.sandboxes.list({ state: "running" });
const mine = await cloud.sandboxes.list({ name: "checkout-api" });
const one = await cloud.sandboxes.get(sandbox.id);

You only ever see sandboxes owned by an organization you belong to.

Name a sandbox

A name is a label you choose. Set it at create, change it later, and filter on it with list. Nothing on the platform reads it, and names are not unique — two sandboxes may share one.

runcloud sandbox create --name checkout-api
runcloud sandbox rename sbx_abc123 checkout-api
runcloud sandbox rename sbx_abc123 ""

await cloud.sandboxes.create({ name: "checkout-api" });
await cloud.sandboxes.rename(sandbox.id, "checkout-api");
await cloud.sandboxes.rename(sandbox.id, "");

Renaming works in every state except destroyed (which returns 409), so a paused sandbox can be re-labelled without resuming it. Names are capped at 128 characters, and an empty name clears the label.

Renaming an exposed sandbox does not move its public hostname. The <name>-box.run.cloud prefix is fixed when you first expose the sandbox; to change it, destroy the sandbox and expose a new one.

This is how you attach an existing sandbox to something on your side — a project, a branch, a customer — without destroying it and paying to boot a replacement. Name it after the thing it belongs to, then find it again:

const [existing] = await cloud.sandboxes.list({ name: `project-${projectId}` });
const sandbox = existing
  ? await cloud.sandboxes.resume(existing.id)
  : await cloud.sandboxes.create({ name: `project-${projectId}` });

Filtering by name returns every live match — names are not unique, and a match may be stopped or archived rather than ready — so check state before you use the result.

Destroy

runcloud sandbox rm sbx_abc123

await cloud.sandboxes.destroy(sandbox.id);

Billing stops when the sandbox is destroyed. Wrap your work in try/finally so a thrown error still tears the sandbox down:

const sandbox = await cloud.sandboxes.create();
try {
  await cloud.sandboxes.exec(sandbox.id, "./run-job.sh");
} finally {
  await cloud.sandboxes.destroy(sandbox.id);
}

Retry-safe creates

If your job runner might retry a create, pass an idempotency key. A repeat with the same key returns the original sandbox instead of spawning (and billing) a second one.

await cloud.sandboxes.create({
  image: "runcloud/agent-base",
  idempotencyKey: jobId,
});

Errors

Status	Meaning
`400`	Malformed `cpu`/`memory`, or an empty `cmd`.
`401`	Missing or invalid API key.
`402`	Organization is over its credit limit or past its payment grace period.
`403`	You are not a member of the requested organization.
`404`	No such sandbox, or it belongs to another organization.
`409`	The sandbox is not running (for example, `exec` on a paused sandbox).
`429`	The organization is at a concurrent resource limit (sandbox count, reserved CPU, or reserved memory). See Limits.

Getting Started

Linux Sandboxes

CI

Integrations

Platform

iOS

Android

Billing

Agents

Create a sandbox

Run a command

List and inspect

Name a sandbox

Destroy

Retry-safe creates

Errors

​Create a sandbox

​Run a command

​List and inspect

​Name a sandbox

​Destroy

​Retry-safe creates

​Errors

Create a sandbox

Run a command

List and inspect

Name a sandbox

Destroy

Retry-safe creates

Errors