# substratusai/sandboxai architecture

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

- Interactive diagram: https://gitdiagram.com/substratusai/sandboxai
- Repository: https://github.com/substratusai/sandboxai

## Overview

##### Main Components
- Containerized Execution Engine: This is the heart of SandboxAI. It manages sandboxed environments where the code and shell commands run in isolation. This is represented by components in both the Python (python/boxd and python/sandboxai) and Go sections (go/sandboxaid).
- API Layer: The RESTful interface is defined (api/v1.yaml) and is implemented in the Go API and Python API submodules. This is the external face of SandboxAI, handling incoming requests and dispatching them to the appropriate backend logic.
- Client SDKs: There are dedicated client implementations in both Python (python/sandboxai/client) and Go (go/client). These provide simple integration for end-users (for example, by pip installing sandboxai-client).
- Supporting Tools and Tests: The repository includes tools (under go/tools) and extensive end-to-end (e2e) tests (in test and go/test/e2e directories) that ensure reliability and proper integration.

- How clients (both Python and Go SDKs) interact with the API layer through RESTful endpoints.
- API’s role in sending execution commands to the underlying sandbox engine, which in turn spins up Docker containers and manages isolated environments.
- Communication flows: from the client SDKs (initiating commands), to the API service, to the container orchestration layer (Docker/Kubernetes), and back (results/results flows).

##### Architectural Patterns and Design Principles
- Separation of concerns: The clear division between client libraries, API endpoints, and container management indicates a modular design.
- Use of containerization to ensure process isolation (Docker and the forthcoming Kubernetes deployment).
- SDK abstraction: The single SDK commands abstract the underlying API complexities from the user.
- Multi-language support: The parallel Python and Go implementations underline the focus on developer flexibility and cross-language compatibility.

##### Incorporate Specific Technologies and Frameworks
- Kubernetes (not yet fully implemented but mentioned as a future multi-node backend).
- RESTful API protocols (with the API defined in api/v1.yaml).
- Python and Go standard libraries & ecosystems.
- GitHub workflows for CI/CD (via .github/workflows) and dependency management files such as go.mod, pyproject.toml, and requirements.txt.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "Client SDKs"
        PyClient["Python Client SDK"]:::client
        GoClient["Go Client SDK"]:::client
    end

    subgraph "API Layer"
        APISpec["API Spec"]:::api
        PythonAPI["Python API"]:::api
        GoAPI["Go API"]:::api
    end

    subgraph "Container Orchestration"
        DockerConf["Docker Configuration"]:::docker
        DockerUtil["Docker Utilities"]:::docker
    end

    subgraph "Containerized Execution Engine"
        subgraph "Python Execution Engine"
            Boxd["Engine: boxd"]:::engine
            Sandbox["Engine: sandboxai"]:::engine
        end
        subgraph "Go Execution Engine"
            SandboxGo["Engine: sandboxaid"]:::engine
            Handler["Handler: sandboxaid/handler"]:::engine
        end
    end

    subgraph "Supporting Tools & Tests"
        GoTools["Go Tools"]:::support
        E2EGo["End-to-End Tests (Go)"]:::support
        E2EPy["End-to-End Tests (Python)"]:::support
        AdditionalTests["Additional Test Cases"]:::support
    end

    %% Flow from Client SDKs to API Layer
    PyClient -->|"request"| PythonAPI
    GoClient -->|"request"| GoAPI

    %% API Layer uses API Spec
    APISpec --- PythonAPI
    APISpec --- GoAPI

    %% API Layer triggers container orchestration
    PythonAPI -->|"executes"| DockerUtil
    GoAPI -->|"executes"| DockerUtil

    %% Container orchestration uses its configuration
    DockerConf --> DockerUtil

    %% Container orchestration launches execution engines
    DockerUtil -->|"runs"| Boxd
    DockerUtil -->|"runs"| Sandbox
    DockerUtil -->|"runs"| SandboxGo
    DockerUtil -->|"runs"| Handler

    %% Execution engines send back responses to API Layer
    Boxd -->|"response"| PythonAPI
    Sandbox -->|"response"| PythonAPI
    SandboxGo -->|"response"| GoAPI
    Handler -->|"response"| GoAPI

    %% API Layer sends responses to Client SDKs
    PythonAPI -->|"responds"| PyClient
    GoAPI -->|"responds"| GoClient

    %% Supporting Tools validate the system components
    E2EGo -.-> GoAPI
    E2EPy -.-> PythonAPI
    AdditionalTests -.-> APISpec
    GoTools -.-> GoAPI

    %% Click Events
    click Boxd "https://github.com/substratusai/sandboxai/blob/main/python/boxd/main.py"
    click Sandbox "https://github.com/substratusai/sandboxai/blob/main/python/sandboxai/sandbox.py"
    click SandboxGo "https://github.com/substratusai/sandboxai/blob/main/go/sandboxaid/main.go"
    click Handler "https://github.com/substratusai/sandboxai/blob/main/go/sandboxaid/handler/handler.go"
    click APISpec "https://github.com/substratusai/sandboxai/blob/main/api/v1.yaml"
    click PythonAPI "https://github.com/substratusai/sandboxai/blob/main/python/sandboxai/api/v1.py"
    click GoAPI "https://github.com/substratusai/sandboxai/blob/main/go/api/v1/generate.go"
    click PyClient "https://github.com/substratusai/sandboxai/blob/main/python/sandboxai/client/v1.py"
    click GoClient "https://github.com/substratusai/sandboxai/blob/main/go/client/v1/client.go"
    click DockerConf "https://github.com/substratusai/sandboxai/blob/main/box.Dockerfile"
    click DockerUtil "https://github.com/substratusai/sandboxai/blob/main/go/sandboxaid/client/docker/docker.go"
    click GoTools "https://github.com/substratusai/sandboxai/blob/main/go/tools/tools.go"
    click E2EGo "https://github.com/substratusai/sandboxai/blob/main/go/test/e2e/client_v1_test.go"
    click E2EPy "https://github.com/substratusai/sandboxai/blob/main/python/sandboxai/test/e2e/test_client_v1.py"
    click AdditionalTests "https://github.com/substratusai/sandboxai/blob/main/test/e2e/run.sh"

    %% Styles
    classDef client fill:#FFCC00,stroke:#000,stroke-width:2px;
    classDef api fill:#66CCFF,stroke:#000,stroke-width:2px;
    classDef engine fill:#CCFFCC,stroke:#000,stroke-width:2px;
    classDef docker fill:#FF9999,stroke:#000,stroke-width:2px;
    classDef support fill:#CCCCCC,stroke:#000,stroke-width:2px;
```
