run-cloud.md

description	Run Cloud provider for ComputeSDK - fast Firecracker microVM sandboxes with configurable resources, filesystem access, and snapshots.
layout	width title description tableOfContents outline pagination metadata tags actions default visible true visible visible true visible true visible true visible true visible true visible true

Run Cloud

Run Cloud provides fast Firecracker microVM sandboxes for AI agents, CI, and untrusted code execution.

Installation & Setup

npm install computesdk @computesdk/run-cloud

Create an API key in the Run Cloud dashboard, then export it:

export RUN_CLOUD_API_KEY=rc_live_your_key

RUN_CLOUD_API_TOKEN is supported as an alias. RUN_CLOUD_API_URL optionally targets a custom Run Cloud deployment.

Usage

import { compute } from 'computesdk';
import { runCloud } from '@computesdk/run-cloud';

compute.setConfig({
  provider: runCloud({
    apiKey: process.env.RUN_CLOUD_API_KEY,
    cpu: 2,
    memory: 4096,
    disk: 40,
  }),
});

const sandbox = await compute.sandbox.create({
  templateId: 'runcloud/agent-base',
  name: 'agent-task',
});

const result = await sandbox.runCommand('node --version');
console.log(result.stdout);

await sandbox.filesystem.writeFile('/tmp/result.txt', result.stdout);

const snapshot = await compute.snapshot.create(sandbox.sandboxId, {
  name: 'after-setup',
});

await sandbox.destroy();

const restored = await compute.sandbox.create({
  snapshotId: snapshot.id,
});

Configuration Options

interface RunCloudConfig {
  apiKey?: string;
  apiUrl?: string;
  fetch?: typeof fetch;
  image?: string;
  cpu?: number;
  memory?: number;
  disk?: number;
  idlePauseSeconds?: number;
  timeout?: number;
  region?: string;
  orgId?: string;
  commandTimeout?: number;
  tunnelTtlSeconds?: number;
}

cpu accepts fractional vCPUs, memory uses MiB, and disk uses GiB. timeout and commandTimeout use milliseconds; idlePauseSeconds and tunnelTtlSeconds use seconds.

Fresh creates accept per-create templateId or image, cpu, memory, disk, idlePauseSeconds, timeoutSeconds, region, name, orgId, and idempotencyKey overrides. Snapshot restores accept cpu, memory, disk, timeoutSeconds, region, and name overrides; options the restore API cannot apply are rejected instead of being silently ignored.

Sandbox-level environment variables are not yet persisted by Run Cloud. Pass command-scoped variables through runCommand:

await sandbox.runCommand('echo "$MODEL"', {
  env: { MODEL: 'gpt-5' },
});

Supported Operations

Method	Supported	Notes
create	✅	Fresh image boot or snapshot restore with resource overrides.
getById	✅	Returns null for missing sandboxes.
list	✅	Lists running sandboxes.
destroy	✅	Idempotent when already deleted.
runCommand	✅	Supports cwd, env, timeout, streaming callbacks, and background mode.
getInfo	✅	Refreshes lifecycle and resource metadata.
getUrl	✅	Opens an expiring capability URL without making the sandbox persistent.
Filesystem	✅	Read, write, mkdir, list, exists, and remove.
Snapshots	✅	Create, list, delete, and restore.

Use sandbox.getInstance() to access the official Run Cloud client and native sandbox record.

Tunnel hostnames are random bearer capabilities. Do not write them to public logs. They expire automatically and are removed when the tunnel or sandbox is deleted.