Sitelet https://github.com/NodeOps-app/createos-sandbox-sdk/commit/1f0ca24707cb8e611cc0c5a018c2467ea45ae843
Skip to content

Commit 1f0ca24

Browse files
pratikbinpratikbin
committed
chore(docs): drop "Firecracker" and "microVM" terminology
Scrub the words "Firecracker" and "microVM" (any casing) from the SDK description, README, docs, examples, llms.txt/llms-full.txt, package keywords, and the CI workflow — the product is described as VM sandboxes, not by the underlying hypervisor. Rename docs/explanation/microvm-sandboxes.md -> vm-sandboxes.md and regenerate the example catalog + llms bundles.
1 parent 60f755b commit 1f0ca24

64 files changed

Lines changed: 190 additions & 193 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/examples.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ name: examples
55
# it, and destroys it in a `finally` block — so a green job means the example
66
# worked against production.
77
#
8-
# Cost note: every run spawns real microVMs and makes paid LLM API calls.
8+
# Cost note: every run spawns real VMs and makes paid LLM API calls.
99
# Triggers are kept deliberate: nightly, manual, and on push to main.
1010
#
1111
# No `pull_request` trigger by design. Examples run arbitrary `bun index.ts`

‎AGENTS.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,13 @@ consumer-facing docs.
77

88
## What this is
99

10-
`createos-sandbox-sdk` — the TypeScript SDK for the `createos-sandbox` microVM sandbox
10+
`createos-sandbox-sdk` — the TypeScript SDK for the `createos-sandbox` VM sandbox
1111
control plane. A hand-written HTTP client: **zero runtime dependencies**,
1212
ESM-only, built with `tsc`. The control plane itself is a separate service
1313
maintained by the NodeOps team; this repository is the client SDK only.
1414

1515
Design rationale — why the handle model, the retry policy and the
16-
deliberate non-goals — lives in `docs/explanation/` (the microVM model,
16+
deliberate non-goals — lives in `docs/explanation/` (the VM model,
1717
handle model, lifecycle, and reliability pages). The internal competitive
1818
analysis of other sandbox SDKs is **not** in this public repo; it lives in
1919
the private `fc` control-plane repo at `docs/sdk-analysis.md`.
@@ -163,3 +163,5 @@ if a build-output regression is a concern.
163163
`POST /v1/sandboxes/:id/tunnel/:port` (keyless port-forward) is an
164164
HTTP-Upgrade endpoint and is intentionally not exposed — it needs a raw
165165
socket, not `fetch`.
166+
167+
- DO not mention "VM" or "VM" in public docs or codebase

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# @nodeops-createos/sandbox
22

3-
TypeScript SDK for the `createos-sandbox` control plane — spawn Firecracker
4-
microVM sandboxes, run commands, move files, expose services, and manage disks
3+
TypeScript SDK for the `createos-sandbox` control plane — spawn VM
4+
sandboxes, run commands, move files, expose services, and manage disks
55
and networks. `createSandbox()` returns a stateful `Sandbox` handle, errors are
66
a typed hierarchy, and the transport retries transient failures automatically.
77

@@ -53,7 +53,7 @@ Full docs follow the [Diátaxis](https://diataxis.fr/) framework and live under
5353
- **[Tutorial](docs/tutorial.md)** — build an AI app generator end to end
5454
- **[How-to guides](docs/how-to/)** — files, lifecycle, services, disks, streaming, errors, observability
5555
- **[API reference](docs/reference/)** — every class, method, and type
56-
- **[Explanation](docs/explanation/)** — the microVM model, the handle model, lifecycle, reliability
56+
- **[Explanation](docs/explanation/)** — the VM model, the handle model, lifecycle, reliability
5757
- **[Examples](docs/examples.md)** — runnable programs, one per directory under [`examples/`](examples/)
5858

5959
For AI agents and tools: the machine-readable index is [`llms.txt`](llms.txt)

‎docs/examples.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,16 @@ Runnable, self-contained programs — one per directory under [`examples/`](../e
1919
| 17 | [17-analyze-data-with-ai](../examples/17-analyze-data-with-ai/) | Upload a CSV, have Claude write the analysis from its schema, read back the chart. | — |
2020
| 18 | [18-text-embeddings-server](../examples/18-text-embeddings-server/) | Serve a CPU embeddings model as a long-lived service over ingress. | — |
2121
| 19 | [19-batch-inference-fanout](../examples/19-batch-inference-fanout/) | Shard a classification job across many sandboxes in parallel. | — |
22-
| 20 | [20-google-adk-agent](../examples/20-google-adk-agent/) | Drive a Google ADK agent whose tools run inside a microVM. | — |
22+
| 20 | [20-google-adk-agent](../examples/20-google-adk-agent/) | Drive a Google ADK agent whose tools run inside a VM. | — |
2323
| 32 | [32-langgraph-sandbox-orchestrator](../examples/32-langgraph-sandbox-orchestrator/) | Model sandbox operations as LangGraph nodes with an OpenAI LLM. | — |
2424
| 33 | [33-codex-cli](../examples/33-codex-cli/) | Run the OpenAI Codex CLI in a sandbox to execute a task. | — |
2525
| 34 | [34-openclaw-gateway](../examples/34-openclaw-gateway/) | Run the OpenClaw gateway over ingress and verify /v1/models. | — |
2626
| 35 | [35-aio-sandbox](../examples/35-aio-sandbox/) | All-in-one tour exercising every core primitive in one run. | — |
27-
| 36 | [36-self-hosted-agent-worker](../examples/36-self-hosted-agent-worker/) | Back a Claude Managed Agent with one persistent microVM for tool execution. | extra setup |
28-
| 37 | [37-self-hosted-sandbox-per-session](../examples/37-self-hosted-sandbox-per-session/) | Back a Claude Managed Agent with a fresh microVM per session. | extra setup |
27+
| 36 | [36-self-hosted-agent-worker](../examples/36-self-hosted-agent-worker/) | Back a Claude Managed Agent with one persistent VM for tool execution. | extra setup |
28+
| 37 | [37-self-hosted-sandbox-per-session](../examples/37-self-hosted-sandbox-per-session/) | Back a Claude Managed Agent with a fresh VM per session. | extra setup |
2929
| 44 | [44-claude-changelog-generator](../examples/44-claude-changelog-generator/) | Clone a public git repo inside a sandbox, run the commit log through the Claude Messages API, and download the generated CHANGELOG.md. | extra setup |
3030
| 45 | [45-claude-github-wiki](../examples/45-claude-github-wiki/) | Clone a public GitHub repo into a sandbox and run a Claude tool-use agent that reads the file tree to answer questions about the codebase. | — |
31-
| 46 | [46-mastra-agent](../examples/46-mastra-agent/) | Install the Mastra TypeScript agent framework inside a createos-sandbox microVM, upload an agent script, run it against an OpenAI-compatible provider, and capture the response. | — |
31+
| 46 | [46-mastra-agent](../examples/46-mastra-agent/) | Install the Mastra TypeScript agent framework inside a createos-sandbox VM, upload an agent script, run it against an OpenAI-compatible provider, and capture the response. | — |
3232
| 47 | [47-effective-agents-patterns](../examples/47-effective-agents-patterns/) | Run three LLM agent patterns (prompt-chaining, routing, parallelization) using the Vercel AI SDK inside a createos-sandbox sandbox, with an OpenAI-compatible model proxy. | — |
3333

3434
## Dev servers & preview URLs
@@ -50,19 +50,19 @@ Runnable, self-contained programs — one per directory under [`examples/`](../e
5050
| --- | --- | --- | --- |
5151
| 01 | [01-hello-world](../examples/01-hello-world/) | Smoke test: create a sandbox, run one buffered command, destroy it. | — |
5252
| 02 | [02-code-interpreter](../examples/02-code-interpreter/) | Upload a Python script, run it, capture stdout/stderr. Includes a streaming variant. | — |
53-
| 11 | [11-tigerfs-postgres-filesystem](../examples/11-tigerfs-postgres-filesystem/) | Run PostgreSQL on a TigerFS filesystem layer in one microVM. | — |
53+
| 11 | [11-tigerfs-postgres-filesystem](../examples/11-tigerfs-postgres-filesystem/) | Run PostgreSQL on a TigerFS filesystem layer in one VM. | — |
5454
| 26 | [26-s3-bucket-mount](../examples/26-s3-bucket-mount/) | Query a public S3 bucket via DuckDB httpfs inside a sandbox. | — |
5555
| 29 | [29-playwright-headless-browser](../examples/29-playwright-headless-browser/) | Run Playwright + headless Chromium to scrape and extract the DOM. | — |
5656
| 31 | [31-git-clone-lsp-typescript](../examples/31-git-clone-lsp-typescript/) | Clone a TS repo and drive typescript-language-server over stdio. | — |
5757
| 41 | [41-python-pdf-extractor](../examples/41-python-pdf-extractor/) | Upload a fillable PDF into a sandbox, pip-install PyMuPDF, extract every form-field name and value to JSON, and download the result — no external API required. | — |
5858
| 42 | [42-doc-to-markdown](../examples/42-doc-to-markdown/) | Upload a local document (HTML, DOCX, PDF, …) into a createos-sandbox sandbox, convert it to Markdown with Microsoft MarkItDown (pip-installed inside the guest), and download the result. | — |
59-
| 43 | [43-crawl4ai-crawler](../examples/43-crawl4ai-crawler/) | Install Crawl4AI and Playwright/Chromium inside a microVM, crawl a public URL to Markdown, download the output to the host. | — |
59+
| 43 | [43-crawl4ai-crawler](../examples/43-crawl4ai-crawler/) | Install Crawl4AI and Playwright/Chromium inside a VM, crawl a public URL to Markdown, download the output to the host. | — |
6060

6161
## Disks, networks & templates
6262

6363
| # | Example | What it shows | Setup |
6464
| --- | --- | --- | --- |
65-
| 07 | [07-docker-custom-template](../examples/07-docker-custom-template/) | Build a custom rootfs template from a Dockerfile, then run containers inside the microVM. | — |
65+
| 07 | [07-docker-custom-template](../examples/07-docker-custom-template/) | Build a custom rootfs template from a Dockerfile, then run containers inside the VM. | — |
6666
| 38 | [38-s3-disk-ffmpeg-transcode](../examples/38-s3-disk-ffmpeg-transcode/) | Register an S3-backed disk, mount at boot, transcode with ffmpeg, detach, destroy. | extra setup |
6767

6868
## Lifecycle, snapshots & cost

docs/explanation/microvm-sandboxes.md renamed to docs/explanation/vm-sandboxes.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# What is a microVM sandbox?
1+
# What is a VM sandbox?
22

3-
A createos-sandbox **sandbox** is a Firecracker microVM — a real virtual machine
3+
A createos-sandbox **sandbox** is a VM — a real virtual machine
44
running its own Linux kernel on KVM hardware virtualization, not a
55
container sharing the host kernel. Each sandbox has its own kernel, its own
66
memory address space, and its own set of virtual devices. That hard
@@ -10,7 +10,7 @@ boundary is the foundation everything else in this platform is built on.
1010

1111
Containers are processes isolated by Linux namespaces and cgroups. They
1212
share the host kernel, so a kernel-level exploit in one container can
13-
escape to every other container and the host. A Firecracker microVM has its
13+
escape to every other container and the host. A VM has its
1414
own kernel and memory; a kernel exploit stays inside the VM. The blast
1515
radius of a compromised sandbox is the sandbox. This property is what makes
1616
it safe to run untrusted or model-generated code — code that, by
@@ -90,7 +90,7 @@ following sequence, which the SDK abstracts into a single awaitable call:
9090
1. **Schedule.** The control plane selects a worker host with enough free
9191
memory for the requested shape and places the sandbox there.
9292

93-
2. **Boot.** Firecracker starts a microVM on that host: it loads the
93+
2. **Boot.** VM starts a VM on that host: it loads the
9494
rootfs, applies the writable overlay, brings up the Linux kernel, and
9595
waits for the in-VM agent to come online.
9696

‎docs/index.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# createos-sandbox SDK
22

3-
The TypeScript SDK for **createos-sandbox** — spawn Firecracker microVM
3+
The TypeScript SDK for **createos-sandbox** — spawn VM
44
sandboxes, run commands, move files, expose services, and orchestrate fleets,
55
from one hand-written `fetch` client with zero runtime dependencies.
66

@@ -10,7 +10,7 @@ import { CreateosSandboxClient } from "createos-sandbox-sdk";
1010
const client = new CreateosSandboxClient();
1111
const sandbox = await client.createSandbox({ shape: "s-4vcpu-4gb", rootfs: "devbox:1" });
1212
try {
13-
const out = await sandbox.runCommand("echo", ["hello from a microVM"]);
13+
const out = await sandbox.runCommand("echo", ["hello from a VM"]);
1414
console.log(out.result.stdout);
1515
} finally {
1616
await sandbox.destroy();
@@ -25,7 +25,7 @@ Vercel Edge, and the browser.
2525

2626
## What you can build
2727

28-
- **Run AI-generated code** safely — an agent writes code, a microVM runs it,
28+
- **Run AI-generated code** safely — an agent writes code, a VM runs it,
2929
you read back the result.
3030
- **Expose a live service** — start a server inside the sandbox and reach it at
3131
a per-sandbox [preview URL](./how-to/expose-a-service.md).
@@ -45,15 +45,15 @@ of documentation for four kinds of need.
4545
| **Get going in 30 seconds** | [Quickstart](./quickstart.md) |
4646
| **Solve a specific problem** | [How-to guides](./how-to/) — files, lifecycle, services, disks, streaming, errors, observability |
4747
| **Look up a method or type** | [API reference](./reference/) — client, sandbox, sub-APIs, errors, types, helpers |
48-
| **Understand how it works** | [Explanation](./explanation/) — microVMs, the handle model, lifecycle, reliability |
48+
| **Understand how it works** | [Explanation](./explanation/) — VMs, the handle model, lifecycle, reliability |
4949
| **Copy a working program** | [Examples](./examples.md) — runnable, one per directory |
5050

5151
## Start here
5252

5353
- New to the SDK? Read the [Quickstart](./quickstart.md), then the
5454
[Tutorial](./tutorial.md).
55-
- New to microVM sandboxes? Read
56-
[What is a microVM sandbox?](./explanation/microvm-sandboxes.md)
55+
- New to VM sandboxes? Read
56+
[What is a VM sandbox?](./explanation/vm-sandboxes.md)
5757
- Building an agent? Jump to the [Tutorial](./tutorial.md) and the
5858
[examples](./examples.md).
5959

‎docs/quickstart.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
The 30-second tour: install, authenticate, spawn a sandbox, run a command,
44
and tear it down. For a full guided lesson, see the
55
[tutorial](./tutorial.md); for the conceptual picture, start with
6-
[what a microVM sandbox is](./explanation/microvm-sandboxes.md).
6+
[what a VM sandbox is](./explanation/vm-sandboxes.md).
77

88
## 1. Install
99

@@ -130,5 +130,5 @@ try {
130130
- [Tutorial: build an AI app generator](./tutorial.md) — the full guided lesson
131131
- [How-to guides](./how-to/) — task-oriented recipes
132132
- [API reference](./reference/) — every class, method, and type
133-
- [Explanation](./explanation/) — the microVM model, lifecycle, and reliability
133+
- [Explanation](./explanation/) — the VM model, lifecycle, and reliability
134134
- [Examples](./examples.md) — runnable, copy-pasteable end-to-end programs

‎docs/tutorial.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
# Tutorial: build an AI app generator
22

33
In this tutorial you will build a small script that takes a plain-English
4-
prompt, asks Claude to write a web app, uploads that app into a live microVM
4+
prompt, asks Claude to write a web app, uploads that app into a live VM
55
sandbox, starts it, and hands you a public URL you can open in a browser.
6-
That is the SDK's flagship loop: **LLM generates → microVM runs → ingress
6+
That is the SDK's flagship loop: **LLM generates → VM runs → ingress
77
serves**.
88

99
**What you'll learn**
@@ -456,7 +456,7 @@ destroy** loop:
456456
your next step on the port actually being bound.
457457
4. The loop is repeatable — re-upload, restart, re-fetch — so iterative
458458
generation works without touching the sandbox plumbing again.
459-
5. `try { … } finally { sandbox.destroy() }` ensures the microVM is always
459+
5. `try { … } finally { sandbox.destroy() }` ensures the VM is always
460460
reclaimed, even when earlier steps throw.
461461

462462
This pattern generalises: swap Claude for any model or codegen pipeline, swap
@@ -473,7 +473,7 @@ the sandbox wiring stays the same.
473473
download artifacts
474474
- [Reference: Sandbox](./reference/sandbox.md) — full method signatures for
475475
`runCommand`, `files`, `previewUrl`, `waitForPortReady`, `destroy`
476-
- [Explanation: microVM sandboxes](./explanation/microvm-sandboxes.md) — why
477-
microVMs, isolation model, cold-start latency
476+
- [Explanation: VM sandboxes](./explanation/vm-sandboxes.md) — why
477+
VMs, isolation model, cold-start latency
478478
- [examples/04-ai-code-agent](../examples/04-ai-code-agent/index.ts) — a
479479
richer tool-use loop where Claude runs code iteratively and reacts to output

‎examples/03-dev-server-preview-url/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* Dev server + preview URL — run an HTTP server inside the sandbox and reach it
33
* from the public internet over per-sandbox ingress. The pattern behind serving
4-
* a live app preview (dev server, web UI) straight out of a microVM.
4+
* a live app preview (dev server, web UI) straight out of a VM.
55
*
66
* Run: bun 03-dev-server-preview-url/index.ts
77
* Needs: CREATEOS_SANDBOX_BASE_URL + CREATEOS_SANDBOX_API_KEY (see .env.example). No external services.

‎examples/04-ai-code-agent/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Claude uses a createos-sandbox sandbox as its code-execution environment. The TypeScript
44
process drives Claude through a `tool_use` loop: Claude emits Python via a
5-
`run_code` tool, this process uploads and runs it in the microVM with
5+
`run_code` tool, this process uploads and runs it in the VM with
66
`runCommand`, feeds the output back, and repeats until Claude stops requesting
77
tools. The canonical "LLM with a code sandbox" pattern.
88

0 commit comments

Comments
 (0)