System Overview

Purpose

This page is the lab's elevator pitch. It describes the system as a whole in one place. The deeper details are in the rest of the 10-architecture/ directory and in the agent and tooling pages.

What the lab is

The lab is a local-first agent ecosystem built for applied learning and real workloads. It is:

• Local-first. Every component runs on the user's machine. There is no cloud control plane.
• Multi-agent. Five specialized agents coordinate through a single Coordinator.
• Tool-driven. Agents invoke typed tools for deterministic work; generative reasoning is reserved for non-deterministic work.
• Auditable. Every mission, every request, every external call is logged.
• Recoverable. Missions can be paused and resumed. Tool failures are retried. The system can be rebuilt from the audit trail.

The lab is not a product. It is a personal research and development environment that has grown into something worth documenting.

Components

The lab has the following top-level components:

Loading diagram…

Gateway

The gateway is the entry point. There are two gateway processes:

The gateways are supervised by launchd (macOS) or systemd (Linux). They restart on crash.

Agents

The five agents are documented in detail in Agents and Roles:

• Coordinator — the main control agent.
• Coding Assistant — the implementation arm.
• Research Worker — the research specialist.
• Media Agent — the entertainment specialist.
• Web Agent — the browser automation capability.

Frameworks

The agents use two major frameworks:

• Research Framework — the orchestrator, phases, schemas, adapters, and domain tools for research.
• Coding Sub-agent — the sandboxed coding CLI that the Coding Assistant delegates to.

Tools

The tools are documented in Tooling Layer. The four categories:

• Media tools — torrent-finder, subtitle-finder, dubbed-finder, media-info, chromecast, vlc, media-playback, media-lab-server.
• Research tools — tavily, duckduckgo, google-search, youtube-transcript, yt-dlp, perplexity.
• Web tools — the OpenClaw browser tool.
• Code tools — codex, git, npm, pytest, etc.

External services

The lab integrates with:

• Model providers — for the Coordinator and the coding sub-agent.
• Search providers — for the research adapters.
• Streaming services — for the Media Agent.
• Devices — for the Media Agent (Cast, VLC hosts).

State

The state is documented in Memory and Context:

• MEMORY.md — the lab's curated long-term memory.
• Daily logs — the raw chronological record.
• Session state — the in-memory state of the current session.
• Skill artifacts — SKILL.md and TOOL.md files.
• Research artifacts — the framework's typed outputs.
• Audit trail — every request, every mission, every external call.

Data flow

A typical request flows through the system as follows:

Loading diagram…

The flow is one-way: the user → Coordinator → agent → framework → tool → external → back. There is no reverse flow.

The detailed data flow is in Data Flow.

Lifecycle

The system has three lifecycles:

1. Session lifecycle. A session starts when the user opens a conversation and ends when the user closes it (or the session times out).
2. Mission lifecycle. A research mission starts when the Research Worker initializes a run and ends when the report is delivered (or the mission fails).
3. Request lifecycle. A request starts when the user sends a message and ends when the Coordinator returns a response.

The lifecycles are managed by the Coordinator and the Research Worker. The session and request lifecycles are short; the mission lifecycle can be minutes to hours.

Constraints

The lab is constrained by:

• Local resources. Memory, CPU, and disk are bounded. The lab's hardware is documented in Environment Variables.
• External rate limits. The model and search providers have rate limits. The lab respects them through the request journal and the token pool.
• User authorization. Some operations require explicit user authorization (e.g., writing to a production system, sending an email).
• Coding sub-agent sandbox. The sub-agent runs in a sandbox. The lab cannot bypass the sandbox without explicit configuration.

The constraints are documented in detail in Security Principles.

Capabilities

The lab can:

• Research. Run multi-phase research missions with typed artifacts and auditable reports.
• Code. Delegate code-writing to a sandboxed sub-agent; review, integrate, and test.
• Media. Search for and play media on local and remote devices (TV, speakers, etc.).
• Web automation. Drive a browser through the accessibility tree; capture, fill, navigate.
• Memory. Remember across sessions with curated long-term memory and daily logs.
• Generation. Generate images and music through the Media Lab Server.

Non-capabilities

The lab explicitly does NOT:

• Run a cloud control plane.
• Authenticate multiple users (single-user assumption).
• Provide a real-time voice interface.
• Expose services to the public internet without explicit user setup.
• Operate production systems.
• Send messages to external channels without explicit user setup.

The non-capabilities are the boundaries that keep the lab safe and predictable.

See also

• System Architecture
• Data Flow
• Framework
• Agents and Roles
• Tooling Layer
• Security Principles