How codesandbox/codesandbox-sdk works
Project type and purpose
• This is a client‐side SDK library (not a full‐stack app) for programmatically creating and interacting with CodeSandbox microVM sandboxes.
• It provides both programmatic interfaces (TypeScript/JavaScript API) and a CLI (under src/bin), targeting both Node.js and browser environments.
• It under-the-hood uses REST (OpenAPI‐generated clients) to manage sandbox lifecycles and a custom WebSocket‐based “pitcher‐protocol” to run commands, manipulate files, ports, etc., inside running sandboxes.
File structure
• Top-level outputs:
• build/*.cjs + esbuild.cjs – compiled CommonJS & ESM bundles
• OpenAPI spec JSON files – definitions for the sandbox REST API
• src/ subdivides into:
• Core abstractions (Sandbox.ts, Sandboxes.ts, VMTier.ts, HostTokens.ts)
• API clients (src/api-clients/client-rest-*): generated REST wrappers per service (container, fs, git, setup, shell, system, task)
• CLI commands (src/bin/commands) + minimal React UI (src/bin/ui) for local dashboard/preview
• Multi-target transports:
– Node agent (src/node/*)
– Browser agent (src/browser/*)
• Shared protocol definitions (src/pitcher-protocol/*), utilities, types
Insights from README
• SDK instantiates:
– CodeSandbox root client holding API token
– Sandbox entity to create/manage individual VM sandboxes
– SandboxClient to run commands, access filesystem, ports, etc.
• Uses OpenAPI for RESTful sandbox lifecycle management, and WebSocket pitcher‐protocol for runtime interactions.
Be detailed
• Every subsystem: CLI commands, UI, core classes, generated REST clients, protocol handlers, transports