RookeryOS — PRD, Architectural Blueprint & MVP

Core Philosophy: The pod is not a script container; it is a fully integrated Operating System. The LLM acts as the Kernel, the browser is the universal API, and human-in-the-loop oversight bridges the gap where automation fails.

Target Branch: rookery-os → main (AgentWorksStudio-2.0) Architecture Reference: ROOKERY-OS.html

1. Product Requirements Document (PRD)

1.1 The Universal Web Interface (Deprecating External APIs)

The Problem: Maintaining 335+ API connectors across 25 industries is unsustainable. Endpoints deprecate, schemas change, rate limits throttle, and storing thousands of raw API keys is a massive security liability.

The Solution: The internal headless browser becomes the primary tool for external interactions. If a human can browse a web app (e.g., QuickBooks, Gmail), the agent can operate it natively. The web was built for human navigation; if the agent can navigate the DOM, it can use any software on earth without needing a custom integration.

Requirement: The agent must be able to parse DOM structures and interact with UI elements to bypass the need for proprietary vendor APIs.

The Problem: Bypassing standard APIs introduces human-centric login barriers (2FA, captchas).

The Solution: Use the existing noVNC integration to stream the headless browser state to the human co-pilot.

Requirement: When an agent encounters a login screen, it must halt and alert the human co-pilot. The human uses the noVNC stream to authenticate natively. Once authenticated, the OS must capture the active session cookie, encrypt it (AES-256-GCM), and persist it to a secure vault to bypass future logins.

Result: You never store a single API key, and you never have to ask a client to generate a developer token for their proprietary software.

1.3 Internal MCP Realignment

The Problem: Existing external MCP servers bloat the platform.

The Solution: External SaaS MCPs are deprecated.

MCP Type	Action	Examples
External SaaS	❌ Deprecate	QuickBooks, Gmail, Salesforce, HubSpot connectors
Internal System	✅ Keep	Lighthouse query, filesystem, terminal, cookie vault
Internal Tool	✅ Keep	Sonar (STT/TTS), Spyglass (screen recording)

MCP becomes the internal hardware bus (querying Lighthouse, reading local filesystem, granting terminal access, pulling data from Sonar), NOT the external network router.

1.4 Tier Isolation

Requirement: The Navigator tier (unpaid client assessment) must operate in a physically isolated Kubernetes namespace to protect the performance and security of the paid production suite.

Aspect	Production Pods	Navigator Pods
Namespace	Per-agent	Shared `navigator`
PVC	Yes (10Gi)	No (ephemeral only)
Sidecar Browser	Yes	No
Cookie Vault	Yes	No
Resources	Tier-based	200m/256Mi → 500m/512Mi
Max Lifetime	Unlimited	24 hours
Network	Full	Platform API + internet only

2. Architectural Blueprint

2.1 Stack Layering

Base OS (The Metal): RookeryOS. A custom, lightweight Linux distribution (hardened debian:bookworm-slim) stripped of unnecessary daemons, optimized strictly for AI runtime execution.

Session Initialization: All sessions bootstrapped exclusively via chelper (coding-helper). Standard CLI flags are deprecated for agent spin-up.

The Kernel (Context & Logic): The LLM acts as the central router. It manages active memory, decides when to swap context to long-term storage, and resolves which tools (Spyglass, standalone Sonar, etc.) to call.

The Sandbox (File & Terminal): The agent operates within a restricted file system. It has native terminal access to execute utilities (curl, grep, python scripts) without requiring custom-built API integrations for basic tasks.

The Internal Browser (The Web Interface): A headless engine running natively inside the RookeryOS pod. Translated via Browser-Use middleware to convert raw DOM into LLM-readable tokenized formats.

2.2 Pod Composition (Sidecar Pattern)

The architecture utilizes a Sidecar Pattern within the Kubernetes pod. Instead of cramming the browser, the VNC server, and the agent into a single bloated container image, responsibilities are split:

┌─────────────────────────────────────────────────────────────┐
│  RookeryOS Pod (Shared Network Namespace)                    │
│                                                              │
│  ┌──────────────────────┐    ┌──────────────────────────┐   │
│  │  Container 1: Kernel │    │  Container 2: Sidecar    │   │
│  │  (The Brain)         │    │  (The Eye/Hand)          │   │
│  │                      │    │                          │   │
│  │  Hudson Gateway      │◄──►│  Chromium (CDP :9222)    │   │
│  │  nginx (:8080)       │    │  noVNC (:6080)           │   │
│  │  s6-overlay v3       │    │  Browser-Use (:9223)     │   │
│  │  chelper bootstrapper│    │  Xvfb + x11vnc           │   │
│  │  Terminal Sandbox    │    │                          │   │
│  │  Internal MCPs       │    │  DOM → LLM tokens        │   │
│  └──────────────────────┘    └──────────────────────────┘   │
│                                                              │
│  Shared: emptyDir /tmp/cdp    PVC: agent-workspace (10Gi)   │
└─────────────────────────────────────────────────────────────┘

2.3 Network & Communication

The agent executes browser commands and receives DOM data via localhost (CDP on :9222). This eliminates external network latency for tool execution.

Agent (LLM) → Hudson Gateway → CDP localhost:9222 → Sidecar Chromium
                                                   ↓
                                            Xvfb → x11vnc → websockify → noVNC → Human
                                                   ↓
                                            Browser-Use :9223 → DOM → LLM-readable tokens

curl vs. Headless Browsing: The terminal allows the agent to decide the most efficient path:

Terminal Path (curl): Simple open REST endpoints → fast, pennies in compute
UI Path (Browser): Complex proprietary CRMs → full rendering with stored cookies

2.4 Output Formatting

Raw logs and JSON payloads are suppressed from the human view. The OS natively formats findings, summaries, and outputs into structured .md and .html files, which Lighthouse renders directly into the operator's dashboard.

3. Minimum Viable Product (MVP) Milestones

Phase 1: The OS Foundation (Core Pod Setup)

Deploy the sidecar pod structure using RookeryOS base image
Ensure chelper successfully provisions the dual-container pod and mounts storage volumes
Validate that the agent can execute local terminal commands (curl, grep) within the sandboxed Container 1

Phase 2: The Visual Bridge (noVNC & Browser)

Install the headless browser and VNC server in Container 2
Establish the localhost CDP connection between agent and browser
Successfully route the noVNC WebSocket stream to the Lighthouse frontend
Allow a human to see the rendered page and take control of mouse/keyboard

Deploy the DOM distillation middleware (Browser-Use)
Build the secure cookie capture mechanism
MVP Test Case: Agent accesses a gated platform → human authenticates via noVNC → terminate pod → spin up new session → agent injects saved cookie → bypasses login screen

Phase 4: Lighthouse Rendering & Navigator Split

Pipe all final agent outputs to the .md / .html rendering engine
Clone the stable deployment specs to spin up the physically isolated Navigator tier
Deprecate external SaaS MCP servers

4. Architecture Trade-Off

Feature	Legacy "API Wrapper" Model	RookeryOS Model
Development Time	Months building 335+ connectors	Zero. If a human can browse it, the agent can use it
Authentication	Complex OAuth; massive liability storing API keys	Human handles 2FA via noVNC; agent saves session cookie
Durability	Breaks instantly on API schema changes	Highly resilient. LLMs adapt to UI updates dynamically
Cost	Vendor API fees and rate limits	Zero API fees. Only pod compute
External Chrome	Depends on external browser APIs	Self-contained. Browser runs inside the pod
Seamless Hand-off	N/A	Human takes control via noVNC without crashing agent context
Ephemeral Persistence	State lost on termination	All context pushed to Lighthouse knowledge graph before termination

5. Migration Checklist

Operational Layer	Current State	Target OS State
Base Configuration	Standard application environment	Hardened, minimal core runtime image (RookeryOS base)
State & Persistence	Local file manipulation inside the application	Ephemeral local sandbox; all permanent artifacts rendered to .md/.html before pod termination
Environmental Isolation	Shared or mixed resources	Complete physical separation between Navigator (free) and production instances

6. Success Metrics

Zero External Chrome Dependencies: The pod must not rely on an external GUI browser API. It must be self-contained.
Seamless Hand-off: A human taking control via the noVNC stream must not crash the agent's context loop. The agent must pause, observe the human DOM changes, and resume upon release.
Ephemeral Persistence: When a chelper session terminates, the RookeryOS pod is destroyed. All vital context must have been successfully pushed to the long-term knowledge graph prior to termination.

References

Architecture Spec: ROOKERY-OS.html
Project Memory: memory/project_rookery-os.md
Tech Stack: TECH-STACK.md
Dual-Container Architecture: DUAL-CONTAINER-ARCHITECTURE.md
Security Model: SECURITY-MODEL.md
Deployment Pipeline: DEPLOYMENT-PIPELINE.md

PreviousPlatform Overview Next Dual-Container Architecture