AgentOS

<div align="center">
  <img src="public/readme/banner.jpeg" alt="AgentOS mission-control interface" width="100%" />

# AgentOS | Mission Control

**Human operating layer for coordinating AI agents, projects, and companies from a single workspace.**

Built on top of OpenClaw, the agent orchestration kernel.

<p>
  <a href="https://sapienx.app/agentos"><strong>Website</strong></a>
  ·
  <a href="https://www.youtube.com/watch?v=ujz-4bYDjdY"><strong>Watch Demo</strong></a>
  ·
  <a href="#why-agentos"><strong>Why AgentOS</strong></a>
  ·
  <a href="#quick-start"><strong>Quick Start</strong></a>
  ·
  <a href="#architecture"><strong>Architecture</strong></a>
  ·
  <a href="#key-features"><strong>Features</strong></a>
  ·
  <a href="#product-highlights"><strong>Highlights</strong></a>
  ·
  <a href="#setup-and-development"><strong>Setup</strong></a>
  ·
  <a href="#roadmap"><strong>Roadmap</strong></a>
</p>

<p>
  <img src="https://img.shields.io/badge/Next.js-16-0b1220?style=for-the-badge&logo=nextdotjs&logoColor=white" alt="Next.js 16" />
  <img src="https://img.shields.io/badge/React-19-07111d?style=for-the-badge&logo=react&logoColor=61dafb" alt="React 19" />
  <img src="https://img.shields.io/badge/TypeScript-Strict-0f172a?style=for-the-badge&logo=typescript&logoColor=3178c6" alt="TypeScript" />
  <img src="https://img.shields.io/badge/OpenClaw-Kernel-111827?style=for-the-badge" alt="OpenClaw kernel" />
  <img src="https://img.shields.io/badge/Local--First-Control_Plane-101828?style=for-the-badge" alt="Local-first control plane" />
</p>

</div>

## Why AgentOS

As AI agents become cheaper to run, the bottleneck shifts from raw orchestration to human control.
Someone still has to decide what matters, inspect active work, route missions, review outputs, and keep multiple projects legible.

Most agent systems expose runtimes, sessions, and CLI primitives.
AgentOS adds the missing operating layer above them: a mission-control interface for humans coordinating teams of agents across real workspaces.

This repository contains the current AgentOS control plane: a Next.js application that sits above OpenClaw and turns live agent state into an operator-facing system for planning, execution, inspection, and workspace management.

## The Problem It Solves

Running one agent is not the hard part.
Operating many agents across many projects is.

AgentOS is built for that coordination problem:

- A human operator needs one place to see workspaces, agents, models, runtimes, and health.
- Missions should map to real project folders, not ephemeral chat threads.
- Runtime output should be inspectable after the fact, including created files and transcript history.
- Agent teams need structure: presets, policies, memory, workspace scaffolds, and repeatable operating conventions.
- As the "one-person company" model emerges, the human needs a control layer, not just an orchestration engine.

## Quick Start

Install the packaged launcher:

```bash
pnpm add -g @sapienx/agentos
agentos start --open
agentos doctor
```

Run the app locally from this repository:

```bash
pnpm install
pnpm dev
```

If OpenClaw is not ready yet, AgentOS starts in an explicit onboarding or fallback path instead of pretending a live control plane exists.

## Architecture

```mermaid
flowchart TD
    Human["Human Operator"] --> AgentOS["AgentOS<br/>control layer / operating layer"]
    AgentOS --> OpenClaw["OpenClaw<br/>agent orchestration kernel"]
    OpenClaw --> Runtime["LLMs, tools, channels, automations, agents"]
```

### Layer Responsibilities

| Layer | Responsibility |
| --- | --- |
| Human operator | Sets direction, reviews work, approves risky actions, and steers the system |
| AgentOS | Presents topology, planning, inspection, workspace bootstrap, settings, and mission dispatch |
| OpenClaw | Owns agent orchestration, gateway state, models, sessions, channels, and execution surfaces |
| LLMs and tools | Perform the underlying reasoning and tool-backed work |

### Control Plane Shape

```mermaid
flowchart LR
    UI["AgentOS UI<br/>Sidebar / Canvas / Inspector / Command Bar / Planner"] --> API["Next.js App Router + API routes"]
    API --> SERVICE["OpenClaw service adapter<br/>snapshot normalization + write actions"]
    SERVICE --> CLI["OpenClaw CLI"]
    CLI --> GATEWAY["Gateway status + presence"]
    CLI --> CONFIG["Agent config + workspace bindings"]
    CLI --> SESSIONS["Sessions + transcript files"]
    SERVICE --> FS["Workspace filesystem + .mission-control state"]
    API --> STREAM["SSE snapshot stream"]
    STREAM --> UI
```

## AgentOS and OpenClaw

OpenClaw is the kernel.
It handles the underlying agent runtime, CLI, gateway, models, sessions, automations, and execution primitives.

AgentOS is the operating layer above it.
It does not replace OpenClaw.
Instead, it reads live OpenClaw state, normalizes it into a control-plane snapshot, and gives the human operator a coherent surface for acting on that state.

In practice, that means:

- OpenClaw remains the source of truth for agents, sessions, models, and gateway status.
- AgentOS translates UI actions into real OpenClaw commands and real filesystem changes.
- AgentOS is intentionally not a mock dashboard; it is a control surface over live operational state.

## How The System Works

1. AgentOS reads live OpenClaw surfaces such as gateway status, agent inventory, config, models, sessions, presence, and transcript files.
2. The service layer normalizes that data into a single `MissionControlSnapshot`.
3. The UI renders that snapshot as a mission-control surface with a topology canvas, sidebar, inspector, and command bar.
4. Operator actions such as mission dispatch, workspace creation, agent updates, planner deploys, gateway changes, or file reveal calls are translated into OpenClaw CLI commands and local filesystem operations.
5. Snapshot state is refreshed over Server-Sent Events so the UI can stay close to real runtime activity.

## Key Features

- Live topology canvas for real workspace -> agent -> runtime relationships.
- Mission dispatch that targets real OpenClaw agents and supports thinking levels.
- Transcript-backed runtime inspection, including final output, warnings, token usage, and created files.
- File reveal actions from the inspector for artifacts written to the local filesystem.
- Workspace wizard with basic create flow and advanced planner mode, including source modes (`empty`, `clone`, `existing`), templates, team presets, model profiles, and kickoff missions.
- Structured workspace scaffolding with `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `TOOLS.md`, `HEARTBEAT.md`, `MEMORY.md`, `docs/`, `memory/`, `deliverables/`, `skills/`, and `.openclaw/project-shell/`.
- Agent creation and editing with policy presets (`worker`, `setup`, `browser`, `monitoring`, `custom`) plus heartbeat, file-access, install-scope, and network controls.
- Guided workspace planner that models company, product, workspace, team, operations, and deploy decisions inside the workspace wizard.
- Planner deploy flows that can turn a plan into a live workspace, agent team, automations, channels, and first missions.
- OpenClaw onboarding, model setup, gateway control, reset, and update flows directly from the UI.
- Configurable gateway endpoint and default workspace root from settings.
- Explicit fallback mode when OpenClaw is unavailable, rather than pretending live control exists.

## Product Highlights

Three flows define the current AgentOS experience:

### One-Click OpenClaw Setup

<img src="public/readme/setup.webp" alt="Guided OpenClaw setup and onboarding flow" width="100%" />

Go from zero to a live control plane in minutes. AgentOS detects what is missing, installs OpenClaw, and guides operators through system and model onboarding without the usual setup friction.

### AI Workspace Architect

<img src="public/readme/create.webp" alt="AI architect flow for creating workspaces, tasks, and agents" width="100%" />

Turn a rough idea into an ope

[truncated…]