@computesdk/createos-sandbox

ComputeSDK provider for CreateOS — NodeOps' createos-sandbox VM sandbox service. Thin adapter over the official @nodeops-createos/sandbox.

Install

npm install computesdk @computesdk/createos-sandbox

Usage

import { compute } from "computesdk";
import { createosSandbox } from "@computesdk/createos-sandbox";

compute.setConfig({
  provider: createosSandbox({
    apiKey: process.env.CREATEOS_SANDBOX_API_KEY,
    baseUrl: process.env.CREATEOS_SANDBOX_BASE_URL,
  }),
});

const sandbox = await compute.instances.create({ memoryMb: 1024, image: "devbox:1" });
const { stdout } = await sandbox.runCommand("echo hello");
await sandbox.filesystem.writeFile("/tmp/x.txt", "hi");
await sandbox.destroy();

Configuration

Capability mapping

createos-sandbox sizes VMs from a shape catalog (not free-form cpu/mem), so create() fetches the live catalog (GET /v1/shapes) and maps ComputeSDK's cpus/memoryMb onto the smallest shape that fits. Pass a provider-specific shape to pin one exactly (skips the catalog fetch). With no size pinned, the default is the smallest live shape with ≥1 GiB RAM. image/runtime map to rootfs; ephemeralDiskMb is passed straight through to disk_mib (the control plane validates it; 0/omitted = the shape's default disk).

Template builds (/v1/templates) are not exposed through the ComputeSDK provider surface — ComputeSDK's public Provider type can't carry the createos-specific dockerfile create option type-safely. Build templates with the native @nodeops-createos/sandbox client (client.templates.create) directly.

Native escape hatch

ComputeSDK's core surface has no pause/resume/fork. Reach the full @nodeops-createos/sandbox Sandbox handle via getInstance():

const native = sandbox.getInstance();
await native.pause();
await native.waitUntilPaused(); // pause() returns while the VM is still "pausing"
const clone = await native.fork();
await native.resume();
await native.attachDisk({ diskId: "my-bucket", mountPath: "/mnt/data" });

Known limitations

• runCommand env/cwd are synthesised — createos-sandbox drops per-exec env server-side, so env/cwd are injected by wrapping the command in an inline sh -c script. Sandbox-level env should be set at create time (envs).
• Snapshots are paused forks — createos forks only from a paused sandbox, so snapshot.create briefly pauses the source, forks it into a paused copy (the snapshot, with its own id) and resumes the source. create({ snapshotId }) forks that copy into a fresh sandbox; snapshot.delete destroys it. A snapshot taken while a process is running captures its memory state too.
• getUrl turns on ingress — sandboxes are created with ingress off (pass ingressEnabled: true to enable it at create); getUrl enables it on demand the first time a URL is requested. Ingress currently serves a non-CA TLS cert and strips the Authorization header upstream — use protocol: "http" / curl -k and don't rely on HTTP auth behind ingress.
• readdir parses ls output — relies on coreutils ls in the rootfs.

License

MIT