Architecture

Hull0 consists of three components: control plane, supervisor, and proxy.

┌─────────────────────────────────────────────────────────────┐
│                      Control Plane                          │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────────┐│
│  │  Auth   │  │ Agents  │  │ Secrets │  │    Approvals    ││
│  └─────────┘  └─────────┘  └─────────┘  └─────────────────┘│
└─────────────────────────────────────────────────────────────┘
                              │
                              │ HTTP
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       Supervisor                            │
│  ┌─────────────────┐  ┌─────────────────┐                  │
│  │ Deploy Poller   │  │ Sandbox Manager │                  │
│  └─────────────────┘  └─────────────────┘                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ spawn
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        Sandbox                              │
│  ┌─────────┐         ┌─────────────────────────────────┐   │
│  │  Agent  │ ──UDS── │           Proxy                 │   │
│  └─────────┘         │  ┌─────┐ ┌─────┐ ┌─────┐       │   │
│                      │  │Allow│→│Rate │→│Taint│→ ...  │   │
│                      │  └─────┘ └─────┘ └─────┘       │   │
│                      └─────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Control Plane

REST API handling:

• User authentication (Cognito OAuth)
• Agent registry (CRUD operations)
• Secret storage (AES-256-GCM encrypted)
• Approval queue (human-in-the-loop)

Exposes internal endpoints for supervisor communication.

Supervisor

Runs on compute nodes. Responsibilities:

• Poll control plane for pending deployments
• Create sandboxes (Linux namespaces, cgroups)
• Spawn proxy processes
• Report agent status back to control plane

Proxy

Runs inside each sandbox alongside the agent. Enforces the manifest through an 8-stage pipeline. Two modes:

• UDS: Agent connects via Unix socket, sends JSON requests
• Transparent: iptables redirects network traffic to proxy

Data Flow

1. User deploys agent via CLI or web
2. Control plane records agent as deploying
3. Supervisor polls, sees pending agent, creates sandbox
4. Proxy starts, loads manifest
5. Agent runs, makes requests through proxy
6. Proxy enforces rules, logs to audit chain
7. User can view status, manage approvals via CLI