# codesandbox/codesandbox-sdk architecture

> Architecture diagram of the GitHub repository codesandbox/codesandbox-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codesandbox/codesandbox-sdk
- Repository: https://github.com/codesandbox/codesandbox-sdk

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Developer Application / Host Environment"
        DeveloperApp["Developer App"]:::frontend
        NodeEnv["Host Env: Node.js/Browser"]:::frontend
    end

    DeveloperApp -->|"imports & invokes"| CodeSandbox
    DeveloperApp -->|"runs CLI"| CLIEntry

    NodeEnv --> AgentClient
    NodeEnv --> BrowserAgentClient

    subgraph "SDK Library"
        subgraph "Domain Layer"
            CodeSandbox["CodeSandbox"]:::domain
            Sandbox["Sandbox"]:::domain
            Sandboxes["Sandboxes"]:::domain
            VMTier["VMTier"]:::domain
            HostTokens["HostTokens"]:::domain
        end

        subgraph "SandboxClient API"
            SandboxClient["SandboxClient"]:::domain
            subgraph "Subclients"
                Commands["commands"]:::domain
                Filesystem["filesystem"]:::domain
                Hosts["hosts"]:::domain
                Ports["ports"]:::domain
                Setup["setup"]:::domain
                Tasks["tasks"]:::domain
                Terminals["terminals"]:::domain
            end
        end

        subgraph "API Clients (REST)"
            REST_Core["Shared REST Client Core"]:::api
            subgraph "Generated REST Clients"
                REST_Container["container"]:::api
                REST_FS["filesystem"]:::api
                REST_Git["git"]:::api
                REST_Setup["setup"]:::api
                REST_Shell["shell"]:::api
                REST_System["system"]:::api
                REST_Task["task"]:::api
            end
        end

        subgraph "Pitcher Protocol"
            PP_Def["Protocol Definitions"]:::protocol
            PP_Types["Protocol Core Types"]:::protocol
            PP_Messages["Protocol Messages"]:::protocol
        end

        subgraph "Transports"
            AgentClient["AgentClient"]:::transport
            WebSocketClient["WebSocketClient"]:::transport
            AgentConnection["AgentConnection"]:::transport
            BrowserAgentClient["BrowserAgentClient"]:::transport
            PreviewScript["Browser Preview Script"]:::transport
        end

        subgraph "CLI & UI"
            CLIEntry["CLI Entry (main.tsx)"]:::cli
            CLICommands["CLI Commands"]:::cli
            CLIDashboard["CLI UI Dashboard"]:::cli
        end
    end

    CodeSandbox -->|"creates|manages"| Sandbox
    Sandbox -->|"collection"| Sandboxes
    CodeSandbox -->|"refines tier"| VMTier
    CodeSandbox -->|"handles tokens"| HostTokens

    SandboxClient --> PP_Def
    PP_Def --> PP_Messages
    PP_Def --> PP_Types

    SandboxClient --> AgentClient
    SandboxClient --> WebSocketClient
    BrowserAgentClient --> PreviewScript

    REST_Core --> REST_Container
    REST_Core --> REST_FS
    REST_Core --> REST_Git
    REST_Core --> REST_Setup
    REST_Core --> REST_Shell
    REST_Core --> REST_System
    REST_Core --> REST_Task

    REST_Container -->|HTTPS| REST_API
    REST_FS -->|HTTPS| REST_API
    REST_Git -->|HTTPS| REST_API
    REST_Setup -->|HTTPS| REST_API
    REST_Shell -->|HTTPS| REST_API
    REST_System -->|HTTPS| REST_API
    REST_Task -->|HTTPS| REST_API

    WebSocketClient -->|WS| WS_Gateway
    BrowserAgentClient -->|WS| WS_Gateway

    subgraph "CodeSandbox Backend"
        REST_API["REST API"]:::backend
        WS_Gateway["WebSocket Gateway"]:::backend
        MicroVM["microVM Infrastructure"]:::infra
    end

    REST_API -->|lifecycle mgmt| MicroVM
    WS_Gateway -->|exec commands| MicroVM
    MicroVM -->|responses| WS_Gateway

    CLIEntry --> CLICommands
    CLICommands --> CLIDashboard
    CLIDashboard --> PreviewScript

    classDef domain fill:#cfe2f3,stroke:#036; 
    classDef api fill:#d9ead3,stroke:#090;
    classDef protocol fill:#f9cb9c,stroke:#e69138;
    classDef transport fill:#fff2cc,stroke:#bf9000;
    classDef cli fill:#f4cccc,stroke:#c00;
    classDef backend fill:#e7e6e6,stroke:#666;
    classDef infra fill:#d0d0d0,stroke:#999;
    classDef frontend fill:#ead1dc,stroke:#a64d79;

    click CodeSandbox "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/index.ts"
    click Sandbox "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/Sandbox.ts"
    click Sandboxes "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/Sandboxes.ts"
    click VMTier "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/VMTier.ts"
    click HostTokens "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/HostTokens.ts"
    click SandboxClient "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/SandboxClient/index.ts"
    click Commands "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/SandboxClient/commands.ts"
    click Filesystem "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/SandboxClient/filesystem.ts"
    click Hosts "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/SandboxClient/hosts.ts"
    click Ports "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/SandboxClient/ports.ts"
    click Setup "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/SandboxClient/setup.ts"
    click Tasks "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/SandboxClient/tasks.ts"
    click Terminals "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/SandboxClient/terminals.ts"
    click REST_Container "https://github.com/codesandbox/codesandbox-sdk/tree/main/src/api-clients/client-rest-container"
    click REST_FS "https://github.com/codesandbox/codesandbox-sdk/tree/main/src/api-clients/client-rest-fs"
    click REST_Git "https://github.com/codesandbox/codesandbox-sdk/tree/main/src/api-clients/client-rest-git"
    click REST_Setup "https://github.com/codesandbox/codesandbox-sdk/tree/main/src/api-clients/client-rest-setup"
    click REST_Shell "https://github.com/codesandbox/codesandbox-sdk/tree/main/src/api-clients/client-rest-shell"
    click REST_System "https://github.com/codesandbox/codesandbox-sdk/tree/main/src/api-clients/client-rest-system"
    click REST_Task "https://github.com/codesandbox/codesandbox-sdk/tree/main/src/api-clients/client-rest-task"
    click REST_Core "https://github.com/codesandbox/codesandbox-sdk/tree/main/src/api-clients/client"
    click AgentClient "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/node/AgentClient.ts"
    click WebSocketClient "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/node/WebSocketClient.ts"
    click AgentConnection "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/node/AgentConnection.ts"
    click BrowserAgentClient "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/browser/BrowserAgentClient.ts"
    click PreviewScript "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/browser/previews/preview-script.ts"
    click CLIEntry "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/bin/main.tsx"
    click CLICommands "https://github.com/codesandbox/codesandbox-sdk/tree/main/src/bin/commands"
    click CLIDashboard "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/bin/ui/Dashboard.tsx"
    click PP_Def "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/pitcher-protocol/index.ts"
    click PP_Types "https://github.com/codesandbox/codesandbox-sdk/blob/main/src/pitcher-protocol/types.ts"
    click PP_Messages "https://github.com/codesandbox/codesandbox-sdk/tree/main/src/pitcher-protocol/messages"
    click Utils "https://github.com/codesandbox/codesandbox-sdk/tree/main/src/utils"
```
