npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@nodeops-createos/sandbox

v0.8.3

Published

Isolated sandboxes for AI agents and untrusted code: create, run commands, egress allowlist, pause/resume/fork, destroy. TypeScript SDK for CreateOS Sandbox.

Readme

@nodeops-createos/sandbox

TypeScript SDK for CreateOS Sandbox — launch isolated sandboxes, run commands, move files, expose services, and manage disks and networks. createSandbox() returns a stateful Sandbox handle, errors are a typed hierarchy, and the transport retries transient failures automatically.

Zero runtime dependencies. ESM-only. Runs on Node 20+, Bun, Deno, Cloudflare Workers, Vercel Edge, and the browser.

Install

npm install @nodeops-createos/sandbox
# or: bun add @nodeops-createos/sandbox

Requires Node 20+ (or any runtime with global fetch, ReadableStream, and AbortSignal.any — Bun, Deno, modern edge runtimes).

Quick start

Run untrusted, model-generated Python with a network allowlist, a timeout, and guaranteed cleanup:

import { CreateosSandboxClient } from "@nodeops-createos/sandbox";

// baseUrl from CREATEOS_SANDBOX_BASE_URL, apiKey from CREATEOS_SANDBOX_API_KEY
const client = new CreateosSandboxClient();

const sandbox = await client.createSandbox({
  shape: "s-1vcpu-1gb",
  rootfs: "devbox:1",
  labels: { team: "backend", environment: "test" },
  // Egress allowlist: the sandbox reaches PyPI and nothing else.
  egress: ["pypi.org:443", "*.pythonhosted.org:443"],
});

try {
  await sandbox.files.upload("/tmp/script.py", "print(sum(range(10)))\n");

  const { result } = await sandbox.runCommand("python3", ["/tmp/script.py"], {
    timeoutMs: 300_000, // 5 minutes, then the request aborts
  });

  console.log(result.stdout, result.exit_code); // "45\n" 0
} finally {
  await sandbox.destroy(); // always tear down — sandboxes bill while running
}

Omit egress (or pass ["*"]) to allow all outbound traffic. For a sandbox that outlives one command — a dev server, a session an agent returns to — let it pause itself when idle instead of destroying it:

const sandbox = await client.createSandbox({
  shape: "s-1vcpu-1gb",
  rootfs: "devbox:1",
  auto_pause_after_seconds: 300, // idle 5 min → paused, disk + memory preserved
});

// ...later, from anywhere:
await sandbox.resume(); // back to running, processes intact

Capture a reusable disk or full snapshot when you need to create new sandboxes from the same prepared state:

let snapshot = await sandbox.createSnapshot({ type: "disk", name: "configured-workspace" });
snapshot = await client.snapshots.get(snapshot.id); // poll until ready
const restored = await client.createSandbox({ snapshot_id: snapshot.id });

Disk snapshots capture the filesystem. Full snapshots also retain memory and must be restored with their captured CPU, memory, and disk sizes. Snapshot capture requires a running source sandbox with no attached external disks. Each account may retain up to five snapshots across both types. See the runnable snapshot example.

Use a checkpoint for fast local file history inside one running sandbox:

const checkpoint = await sandbox.checkpoints.create({
  path: "/workspace/project",
  name: "before-update",
});
await sandbox.checkpoints.restore(checkpoint.id);
await sandbox.checkpoints.delete(checkpoint.id);

Checkpoints restore to their original path, do not capture memory, and disappear with the sandbox. System directories, mount points, overlapping paths, and paths containing special files or hard links are rejected. See the checkpoint example.

baseUrl defaults to the production CreateOS Sandbox API; override it via the constructor or CREATEOS_SANDBOX_BASE_URL. createSandbox blocks until the sandbox reaches running. Shapes, quotas, and concurrency caps are listed in Concepts.

Documentation

Full docs follow the Diátaxis framework and live under docs/:

  • Quickstart — install, authenticate, first sandbox
  • Tutorial — build an AI app generator end to end
  • How-to guides — files, lifecycle, services, disks, streaming, errors, observability
  • API reference — every class, method, and type
  • Explanation — the sandbox model, the handle model, lifecycle, reliability
  • Examples — runnable programs, one per directory under examples/

For AI agents and tools: the machine-readable index is llms.txt and the full corpus is bundled in llms-full.txt (llmstxt.org).

About CreateOS

CreateOS is the execution and governance platform for production AI agents and apps. This SDK exposes CreateOS Sandbox for agent runtimes, code execution, preview services, persistent disks, and networked sandbox workflows.

For product updates and engineering notes, read the CreateOS Sandbox docs and blog.

Key facts

  • Zero runtime dependencies, ESM-only — a hand-written fetch client.
  • Typed errors — a CreateosSandboxError hierarchy with HTTP status → class mapping. See errors.
  • Automatic retries — idempotent requests retry on transient failures with backoff, jitter, and Retry-After. See reliability.
  • Streaming, ingress, snapshots — NDJSON command streaming, per-sandbox preview URLs, and pause / fork / resume.
  • Delegated access — issue, inspect, rotate, or disable a token scoped to one sandbox. See the example.

The CreateOS Sandbox family

One control plane, six SDKs, a CLI, the public docs and the agent integrations, kept behaviourally in step. A change to any shared surface is expected to ripple across the rest.

| repo | what it is | package | | --- | --- | --- | | createos-go-sdk | Go SDK | github.com/NodeOps-app/createos-go-sdk | | createos-python-sdk | Python SDK | createos-sandbox | | createos-rust-sdk | Rust SDK | createos | | createos-csharp-sdk | C# / .NET SDK | CreateOS.Sandbox | | createos-java-sdk | Java SDK | sh.createos:createos-java-sdk | | createos-cli | Go CLI (createos) | — | | createos-v2-landing | public docs — apps/docs/src/pages/Sandbox/ | — | | createos-plugin | integrations monorepo — plugins for 8 agent hosts | — |

Working in this repository? AGENTS.md carries the full cross-repo map and the ripple protocol.

Contributing

Working in this repository? See AGENTS.md for the contributor and agent guide. Commits are gated by .pre-commit-config.yaml (lint, format, typecheck, tests, docs-sync).

License

See LICENSE.