# omjikush09/sandbox-infra architecture

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

- Interactive diagram: https://gitdiagram.com/omjikush09/sandbox-infra
- Repository: https://github.com/omjikush09/sandbox-infra

## Overview

#### Purpose and Entry Points
This is an experimental Firecracker-based sandbox platform. It provisions a nested-virtualization-capable AWS host, maintains warm microVMs, and executes submitted JavaScript inside a guest through an in-guest agent.

Primary runnable services:
- Host-side execution API and VM pool: `packages/vm/main.go`
- Guest execution daemon: `packages/envd/main.go`
- Infrastructure provisioning: `infra/main.tf`
- A Next.js frontend may act as a client surface: `apps/frontend/app/page.tsx`

#### Host Execution API and Request Routing
The VM service exposes the host-facing execution endpoint, described as `POST /api/execute` on port 8000 with CORS enabled. Its router delegates requests to a warm available VM rather than creating a VM per request.

Key paths:
- `packages/vm/router/start.go`
- `packages/vm/controller/controller.go`
- `packages/vm/main.go`

This boundary separates untrusted workload requests from host-level Firecracker lifecycle and networking operations.

#### VM Pool and Lifecycle Management
A pool manager targets eight idle microVMs. It checks out a VM for execution and handles cleanup/recovery after use. Per-VM state includes writable rootfs copies, Firecracker processes/API sockets, TAP devices, guest IP allocation, and user/request association.

Key paths:
- `packages/vm/vmpool/vmpool.go`
- `packages/vm/vmpool/vmpoolManager.go`
- `packages/vm/userData/userManager.go`

The pool is the core capacity and isolation control point; exhaustion, lifecycle failures, and teardown occur here rather than in the guest daemon.

#### Firecracker Startup and Host Networking
VM startup launches Firecracker with a per-VM Unix API socket, configures machine resources, boot source, root drive, network interface, and starts the instance through Firecracker’s API. Host networking creates TAP devices and supports forwarding/NAT so the host proxy can reach each guest.

Key paths:
- `packages/vm/start/start.go`
- `packages/vm/firecraker/client.go`
- `packages/vm/utils/network.go`

This layer requires Linux/KVM and installed `firecracker`/`jailer`; it is not portable to ordinary application hosting environments.

#### Guest Agent and Workload Execution
Each guest runs `envd`, a Fiber HTTP daemon on port 3000. The host forwards execution work into the guest; `envd` accepts JavaScript code, writes it to `code.js`, invokes `bun run`, and returns stdout, stderr, exit code, and error data.

Key paths:
- `packages/envd/router/router.go`
- `packages/envd/controllers/execute.go`
- `packages/envd/services/javascript.go`

The guest boundary contains code execution, while the host service owns VM allocation and host resources.

#### Artifacts, Bootstrap, and External Dependencies
On VM-service startup, host preparation uses `/home/ubuntu/firecracker-lab`, obtains a rootfs from S3 when absent, obtains a Firecracker quickstart kernel, and creates per-VM writable root filesystems.

Key paths:
- `packages/vm/main.go`
- `packages/vm/start/start.go`
- `.github/workflows/buildrootfs.yml`

Material dependencies are AWS S3 for rootfs distribution, Bun in guests, Firecracker/jailer, Linux TAP/IP forwarding/NAT, and KVM nested virtualization.

#### AWS Infrastructure
Terraform provisions the EC2 execution host, security group, and bootstrap flow. The EC2 setup installs Firecracker/jailer and enables the host configuration needed for nested virtualization. AWS credentials and an EC2 key pair are external prerequisites.

Key paths:
- `infra/main.tf`
- `infra/modules/ec2/main.tf`
- `infra/modules/ec2/init.sh`

`demon/`, `packages/orchestator/`, and the root `main.go` are currently placeholders rather than active architecture paths.

Main entry points: [`packages/vm/start/start.go`](https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/start/start.go) (Firecracker startup), [`packages/envd/router/router.go`](https://github.com/omjikush09/sandbox-infra/blob/main/packages/envd/router/router.go) (envd guest daemon), [`packages/vm/controller/controller.go`](https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/controller/controller.go) (Execution controller), [`packages/vm/vmpool/vmpoolManager.go`](https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/vmpool/vmpoolManager.go) (Warm VM pool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_infra["AWS Infrastructure"]
  node_terraform["Terraform provisioning<br/>infrastructure<br/>[main.tf]"]
  node_ec2_module["EC2 host module<br/>Terraform module<br/>[main.tf]"]
  node_host_bootstrap["Host bootstrap<br/>init script<br/>[init.sh]"]
  node_aws_ec2{{"AWS EC2 execution host<br/>compute host"}}
end

subgraph group_host["Execution Host"]
  node_execution_api["VM execution API<br/>Go service<br/>[main.go]"]
  node_request_router["Request router<br/>HTTP routing<br/>[start.go]"]
  node_execution_controller["Execution controller<br/>request controller<br/>[controller.go]"]
  node_vm_pool["Warm VM pool<br/>capacity manager<br/>[vmpoolManager.go]"]
  node_vm_state["Per-VM state<br/>VM lifecycle state<br/>[vmpool.go]"]
  node_user_manager["Request association<br/>user manager<br/>[userManager.go]"]
  node_firecracker_startup["Firecracker startup<br/>VM launcher<br/>[start.go]"]
  node_host_networking["TAP and NAT networking<br/>host networking<br/>[network.go]"]
  node_firecracker{{"Firecracker / jailer<br/>microVM runtime<br/>[client.go]"}}
end

subgraph group_guest["Firecracker Guest"]
  node_envd["envd guest daemon<br/>Fiber HTTP daemon<br/>[router.go]"]
  node_execute_handler["Guest execute handler<br/>execution endpoint<br/>[execute.go]"]
  node_bun_executor["Bun JavaScript executor<br/>workload runner<br/>[javascript.go]"]
end

subgraph group_artifacts["Build &amp; Artifacts"]
  node_rootfs_build["Rootfs build workflow<br/>CI workflow<br/>[buildrootfs.yml]"]
  node_s3_rootfs[("S3 rootfs artifact<br/>artifact storage")]
  node_kernel["Quickstart kernel<br/>boot artifact"]
end

node_frontend["Next.js frontend<br/>client surface<br/>[page.tsx]"]

node_frontend -->|"POST /api/execute"| node_execution_api
node_terraform -->|"applies"| node_ec2_module
node_ec2_module -->|"provisions"| node_aws_ec2
node_host_bootstrap -->|"configures"| node_aws_ec2
node_aws_ec2 -->|"runs"| node_execution_api
node_execution_api -->|"serves"| node_request_router
node_request_router -->|"dispatches"| node_execution_controller
node_execution_controller -->|"checks out VM"| node_vm_pool
node_vm_pool -->|"manages"| node_vm_state
node_user_manager -->|"associates request"| node_vm_state
node_vm_pool -->|"creates and recovers"| node_firecracker_startup
node_firecracker_startup -->|"configures via API"| node_firecracker
node_firecracker_startup -->|"creates guest connectivity"| node_host_networking
node_firecracker -->|"runs guest"| node_envd
node_execution_controller -->|"forwards execution"| node_envd
node_host_networking -->|"proxies via TAP/NAT"| node_envd
node_envd -->|"routes request"| node_execute_handler
node_execute_handler -->|"executes JavaScript"| node_bun_executor
node_rootfs_build -->|"publishes"| node_s3_rootfs
node_s3_rootfs -->|"downloads rootfs"| node_firecracker_startup
node_kernel -->|"boot source"| node_firecracker_startup

click node_frontend "https://github.com/omjikush09/sandbox-infra/blob/main/apps/frontend/app/page.tsx"
click node_terraform "https://github.com/omjikush09/sandbox-infra/blob/main/infra/main.tf"
click node_ec2_module "https://github.com/omjikush09/sandbox-infra/blob/main/infra/modules/ec2/main.tf"
click node_host_bootstrap "https://github.com/omjikush09/sandbox-infra/blob/main/infra/modules/ec2/init.sh"
click node_execution_api "https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/main.go"
click node_request_router "https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/router/start.go"
click node_execution_controller "https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/controller/controller.go"
click node_vm_pool "https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/vmpool/vmpoolManager.go"
click node_vm_state "https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/vmpool/vmpool.go"
click node_user_manager "https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/userData/userManager.go"
click node_firecracker_startup "https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/start/start.go"
click node_host_networking "https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/utils/network.go"
click node_firecracker "https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/firecraker/client.go"
click node_envd "https://github.com/omjikush09/sandbox-infra/blob/main/packages/envd/router/router.go"
click node_execute_handler "https://github.com/omjikush09/sandbox-infra/blob/main/packages/envd/controllers/execute.go"
click node_bun_executor "https://github.com/omjikush09/sandbox-infra/blob/main/packages/envd/services/javascript.go"
click node_rootfs_build "https://github.com/omjikush09/sandbox-infra/blob/main/.github/workflows/buildrootfs.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_terraform,node_ec2_module,node_host_bootstrap,node_aws_ec2 toneBlue
class node_execution_api,node_request_router,node_execution_controller,node_vm_pool,node_vm_state,node_user_manager,node_firecracker_startup,node_host_networking,node_firecracker toneAmber
class node_envd,node_execute_handler,node_bun_executor toneMint
class node_rootfs_build,node_s3_rootfs,node_kernel toneRose
class node_frontend toneNeutral
```

## Components

### AWS Infrastructure

- [Terraform provisioning](https://github.com/omjikush09/sandbox-infra/blob/main/infra/main.tf): infrastructure · `infra/main.tf`
- [EC2 host module](https://github.com/omjikush09/sandbox-infra/blob/main/infra/modules/ec2/main.tf): Terraform module · Provisions the execution host and security group. · `infra/modules/ec2/main.tf`
- [Host bootstrap](https://github.com/omjikush09/sandbox-infra/blob/main/infra/modules/ec2/init.sh): init script · Installs host dependencies and configures nested virtualization support. · `infra/modules/ec2/init.sh`
- **AWS EC2 execution host**: compute host

### Execution Host

Linux EC2 host with KVM nested virtualization.

- [VM execution API](https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/main.go): Go service · Hosts POST /api/execute on port 8000. · `packages/vm/main.go`
- [Request router](https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/router/start.go): HTTP routing · Routes execution requests to a warm VM. · `packages/vm/router/start.go`
- [Execution controller](https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/controller/controller.go): request controller · `packages/vm/controller/controller.go`
- [Warm VM pool](https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/vmpool/vmpoolManager.go): capacity manager · Maintains eight idle microVMs and manages checkout, recovery, and teardown. · `packages/vm/vmpool/vmpoolManager.go`
- [Per-VM state](https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/vmpool/vmpool.go): VM lifecycle state · Tracks writable rootfs, process/socket, TAP, guest IP, and request ownership. · `packages/vm/vmpool/vmpool.go`
- [Request association](https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/userData/userManager.go): user manager · `packages/vm/userData/userManager.go`
- [Firecracker startup](https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/start/start.go): VM launcher · Configures and starts each microVM through its Unix API socket. · `packages/vm/start/start.go`
- [TAP and NAT networking](https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/utils/network.go): host networking · Connects the host proxy to guest IPs. · `packages/vm/utils/network.go`
- [Firecracker / jailer](https://github.com/omjikush09/sandbox-infra/blob/main/packages/vm/firecraker/client.go): microVM runtime · Requires Linux, KVM, and nested virtualization. · `packages/vm/firecraker/client.go`

### Firecracker Guest

- [envd guest daemon](https://github.com/omjikush09/sandbox-infra/blob/main/packages/envd/router/router.go): Fiber HTTP daemon · Accepts execution work on port 3000. · `packages/envd/router/router.go`
- [Guest execute handler](https://github.com/omjikush09/sandbox-infra/blob/main/packages/envd/controllers/execute.go): execution endpoint · `packages/envd/controllers/execute.go`
- [Bun JavaScript executor](https://github.com/omjikush09/sandbox-infra/blob/main/packages/envd/services/javascript.go): workload runner · Writes code.js, runs bun run, and returns process results. · `packages/envd/services/javascript.go`

### Build & Artifacts

- [Rootfs build workflow](https://github.com/omjikush09/sandbox-infra/blob/main/.github/workflows/buildrootfs.yml): CI workflow · Builds the guest root filesystem artifact. · `.github/workflows/buildrootfs.yml`
- **S3 rootfs artifact**: artifact storage · Supplies the rootfs when absent on the host.
- **Quickstart kernel**: boot artifact

### Other components

- [Next.js frontend](https://github.com/omjikush09/sandbox-infra/blob/main/apps/frontend/app/page.tsx): client surface · `apps/frontend/app/page.tsx`

## Connections

- Next.js frontend → VM execution API: POST /api/execute
- Terraform provisioning → EC2 host module: applies
- EC2 host module → AWS EC2 execution host: provisions
- Host bootstrap → AWS EC2 execution host: configures
- AWS EC2 execution host → VM execution API: runs
- VM execution API → Request router: serves
- Request router → Execution controller: dispatches
- Execution controller → Warm VM pool: checks out VM
- Warm VM pool → Per-VM state: manages
- Request association → Per-VM state: associates request
- Warm VM pool → Firecracker startup: creates and recovers
- Firecracker startup → Firecracker / jailer: configures via API
- Firecracker startup → TAP and NAT networking: creates guest connectivity
- Firecracker / jailer → envd guest daemon: runs guest
- Execution controller → envd guest daemon: forwards execution
- TAP and NAT networking → envd guest daemon: proxies via TAP/NAT
- envd guest daemon → Guest execute handler: routes request
- Guest execute handler → Bun JavaScript executor: executes JavaScript
- Rootfs build workflow → S3 rootfs artifact: publishes
- S3 rootfs artifact → Firecracker startup: downloads rootfs
- Quickstart kernel → Firecracker startup: boot source