omjikush09/sandbox-infra

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.