Try AgentOS in 5 minutes

Install AgentOS:

curl -fsSL https://raw.githubusercontent.com/SapienXai/AgentOS/main/install.sh | bash

Or use a package manager:

pnpm add -g @sapienx/agentos

Open the UI:

agentos start --open

Verify the local runtime:

agentos status
agentos doctor

First thing to try:

• Open the AgentOS UI.
• Check the OpenClaw onboarding state.
• Create or inspect a workspace.
• Create an agent or use the guided workspace flow.
• Dispatch a mission.
• Inspect the runtime output or transcript.

If OpenClaw is already installed, AgentOS connects to the live control plane and shows the current Gateway, models, agents, and runtimes.
If OpenClaw is missing or not ready yet, AgentOS opens in an explicit unavailable/onboarding state instead of showing a fake live state.

Product Highlights

The screenshots below show the current product flow in the order a new visitor is most likely to explore it.

Launchpad Guided onboarding for OpenClaw, models, and the first workspace.	Control Plane Live graph, task flow, and inspector visibility in one place.
Agent Builder Create agents from scratch, presets, or imports.	Agent Chat Talk to agents directly and turn intent into action.
Add Models Connect providers and discover models without leaving AgentOS.	Workspace Wizard Shape a workspace from one prompt and a guided flow.
Workspace Surfaces Connect Telegram, Discord, Slack, and more to every workspace.

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 control-plane 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

Use the packaged launcher:

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

Run the app locally from this repository:

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

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

flowchart LR
    UI["AgentOS UI<br/>Sidebar / Canvas / Inspector / Command Bar / Planner"] --> API["Next.js App Router + API routes"]
    API --> APP["OpenClaw application services<br/>workspace, agent, mission, runtime, settings"]
    APP --> ADAPTER["OpenClawAdapter<br/>stable compatibility boundary"]
    ADAPTER --> CLIENT["OpenClawGatewayClient<br/>Gateway-first client"]
    CLIENT --> GATEWAY["OpenClaw Gateway RPC + WebSocket events"]
    CLIENT --> CLI["OpenClaw CLI fallback<br/>install, recovery, unsupported operations"]
    GATEWAY --> STATE["Gateway state<br/>models, agents, sessions, channels, skills, approvals, config"]
    CLI --> STATE
    APP --> 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 gateway state, models, agents, sessions, channels, skills, approvals, config, and runtime execution.
• AgentOS uses native OpenClaw Gateway RPC first for supported operations.
• AgentOS keeps the OpenClaw CLI as fallback for install, recovery, gateway process control, and unsupported or older Gateway methods.
• AgentOS translates UI actions into OpenClaw Gateway calls, documented CLI fallbacks, and real filesystem changes.
• AgentOS is intentionally not a mock dashboard; it is a control surface over live operational state.

Compatibility / Tested Runtime

AgentOS is Gateway-first on top of OpenClaw. Use agentos doctor and the in-app diagnostics panel to confirm the installed OpenClaw version, Gateway protocol range, native auth state, model readiness, and fallback activity before dispatching real missions.

The 0.6.8 release expects Node.js 24 or newer and the OpenClaw supported baseline from lib/openclaw/versions.ts. If compatibility is degraded, update OpenClaw, repair Gateway token/device access, restart the Gateway, and re-run agentos doctor --deep.

Current Compatibility Notes

• AgentOS uses OpenClaw Gateway-first transport by default. CLI fallback remains explicit and visible for install, recovery, Gateway process control, older or unsupported Gateway methods, malformed responses, scope limits, and unavailable native auth.
• Accounts and browser profiles are an MVP bridge. AgentOS can read OpenClaw browser profiles, start or attach a reported profile, open a login target, and enforce AgentOS access rules before account-target task launch. OpenClaw does not yet expose typed browser-profile dispatch, verified website account identity, or a direct browser-profile parameter for mission dispatch, so AgentOS passes selected profile/session context to eligible browser-capable agents.
• requires_approval account access rules are intentionally blocked until approval dispatch exists. They are persisted as policy state but cannot run a task yet.
• Surface repair is preview-first. Apply only after reviewing the dry-run audit, backup path, affected config paths, and restore instructions.
• agentos doctor --deep is the release-readiness diagnostic for Gateway protocol, native auth, scopes, required methods, config access, schema/patch support, channel status, model readiness, fallback count, and the last native failure.
• Package release checks are covered by pnpm check:release and pnpm smoke:agentos-package; use the clean-install smoke checklist before publishing or announcing a release.

Security Model

AgentOS is local-first and is intended to bind to loopback by default. Packaged AgentOS generates an API token under the local runtime directory, starts the server with token authentication, and the launcher opens an authenticated local URL. API routes are protected centrally before route handlers run. Remote OpenClaw Gateway URLs are blocked by default unless AGENTOS_ALLOW_REMOTE_GATEWAY_URL=1 is set explicitly. Sensitive local config/auth files are written with owner-only permissions where applicable. Do not expose AgentOS publicly without your own network controls, access policy, and monitoring.

How The System Works

1. AgentOS detects the OpenClaw version, Gateway protocol, auth mode, and advertised RPC capabilities.
2. AgentOS reads live OpenClaw surfaces through Gateway-first RPC calls, with CLI fallback when the Gateway is unavailable, scope-limited, malformed, or does not support a method yet.
3. The application layer normalizes gateway state, sessions, local transcripts, workspace metadata, and AgentOS sidecar state into a single MissionControlSnapshot.
4. The UI renders that snapshot as a control-plane surface with a topology canvas, sidebar, inspector, and command bar.
5. Operator actions such as mission dispatch, workspace creation, agent updates, planner deploys, gateway changes, or file reveal calls pass through the OpenClaw adapter boundary before touching Gateway RPC, CLI fallback, or local filesystem state.
6. Gateway WebSocket events and Server-Sent Events keep runtime and task views close to live OpenClaw activity without replacing existing snapshot rendering.

Key Features

• Live topology canvas for real workspace -> agent -> runtime relationships.
• Gateway-first mission dispatch that targets real OpenClaw agents and supports thinking levels.
• Transcript-backed runtime inspection, including final output, warnings, token usage, and created files.
• Persistent Gateway event bridge for chat, tool, log, session, and approval activity where supported by OpenClaw.
• 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, USER.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 diagnostics, native auth repair, reset, and update flows directly from the UI.
• Capability diagnostics for Gateway protocol, auth mode, supported RPC methods, config schema/patch support, channel support, skills support, approvals support, and update support.
• Gateway-first config reads and patch/apply writes with base-hash concurrency protection and redacted-secret safety.
• Configurable gateway endpoint and default workspace root from settings.
• Explicit fallback mode when OpenClaw is unavailable, rather than pretending live control exists.

What works today / What is coming next

What works today

• Local AgentOS control plane built with Next.js.
• OpenClaw-aware onboarding and fallback state.
• Workspace overview and live control-plane snapshot.
• Agent creation and editing with presets and policies.
• Workspace creation and guided workspace wizard.
• Gateway-first mission dispatch to OpenClaw-backed agents.
• Runtime and transcript inspection.
• Gateway event bridge for supported OpenClaw chat, tool, log, session, and approval events.
• Gateway diagnostics, capability matrix, native auth repair, and control actions.
• Local-first settings for gateway endpoint and workspace root.
• Accounts page for OpenClaw browser-profile login targets, with AgentOS-side access rules and clear browser-profile dispatch limitations.
• Install paths through the release installer and package manager.

What is coming next

• Deeper Telegram and Discord operation jobs.
• More complete approval history and audit trails.
• Stronger recurring workflow and job management.
• Richer model and provider setup guidance.
• More workspace and agent preset examples.
• Better remote or multi-host OpenClaw management.
• More durable analytics and historical runtime views.

UI Surfaces

Surface	Purpose
MissionSidebar	Gateway diagnostics, workspace navigation, models, agents, and workspace or agent CRUD
MissionCanvas	Visual topology for workspaces, agents, and runtimes with selection and mission feedback
InspectorPanel	Detailed inspection of selected entities, transcript output, raw payloads, and created files
CommandBar	Mission composition, agent targeting, thinking level selection, refresh, and quick suggestions
WorkspaceWizardDialog	Handle both basic workspace creation and advanced planner-driven workspace design and deploy
OpenClawOnboarding	Detect, install, start, verify OpenClaw, and guide model readiness when the local machine is not ready
ResetDialog	Preview AgentOS reset or full uninstall actions and stream execution progress and logs

Repository Map (Key Files)

app/
  api/
    agents/
    diagnostics/
    files/reveal/
    gateway/control/
    mission/
    onboarding/
    onboarding/models/
    planner/
    reset/
    runtimes/[runtimeId]/
    settings/
    snapshot/
    stream/
    system/open-terminal/
    update/
    workspaces/
  layout.tsx
  page.tsx

components/mission-control/
  canvas.tsx
  command-bar.tsx
  create-agent-dialog.tsx
  inspector-panel.tsx
  mission-control-shell.tsx
  openclaw-onboarding.tsx
  operation-progress.tsx
  reset-dialog.tsx
  sidebar.tsx
  nodes/
  workspace-wizard/
    workspace-wizard-dialog.tsx
    workspace-wizard-draft-pane.tsx
    workspace-wizard-header.tsx
    wizard-composer.tsx
    wizard-message-list.tsx
    wizard-suggestion-chips.tsx

hooks/
  use-mission-control-data.ts
  use-workspace-wizard-draft.ts

lib/openclaw/
  agent-heartbeat.ts
  agent-presets.ts
  cli.ts
  fallback.ts
  operation-progress.ts
  planner.ts
  planner-core.ts
  planner-presenters.ts
  presenters.ts
  readiness.ts
  reset.ts
  service.ts
  types.ts
  adapter/
  application/
  client/
  domains/
  state/
  workspace-presets.ts
  workspace-wizard-inference.ts
  workspace-wizard-mappers.ts

packages/agentos/
  bin/
  scripts/
  README.md
  package.json

This is a representative map of the current control-plane code, not an exhaustive file listing.
Many internal files still use legacy mission-control naming.

Setup And Development

Prerequisites

• Node.js 24 or newer
• pnpm
• OpenClaw installed locally and reachable on PATH

If OpenClaw is installed in a non-standard location:

export OPENCLAW_BIN=/absolute/path/to/openclaw

Install

GitHub Release installer:

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/SapienXai/AgentOS/main/install.sh | bash
agentos start --open
agentos stop
agentos doctor

Windows PowerShell:

iwr https://raw.githubusercontent.com/SapienXai/AgentOS/main/install.ps1 | iex
agentos start --open
agentos stop
agentos doctor

Install a specific published version:

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/SapienXai/AgentOS/main/install.sh | AGENTOS_VERSION=0.6.8 bash

Windows PowerShell:

$env:AGENTOS_VERSION='0.6.8'; iwr https://raw.githubusercontent.com/SapienXai/AgentOS/main/install.ps1 | iex

Package manager install:

pnpm add -g @sapienx/agentos
# or
npm install -g @sapienx/agentos

agentos start --open
agentos stop
agentos doctor

Stop a running server:

agentos stop

Uninstall:

agentos uninstall

If AgentOS was installed with pnpm or npm, remove it with your package manager instead:

pnpm remove -g @sapienx/agentos
# or
npm uninstall -g @sapienx/agentos

Local development:

pnpm install
openclaw --version
openclaw gateway status --json

If the gateway service is missing or not loaded:

openclaw gateway install --json
openclaw gateway status --json

Releases

Push a tag in the format below to build platform-specific release assets on GitHub Releases:

pnpm check:release
pnpm smoke:agentos-package
git tag agentos-v0.6.8
git push origin agentos-v0.6.8

packages/agentos/package.json is the published CLI/package version source. The root package is private and may keep a separate workspace app version.

The release workflow uploads:

• agentos-darwin-arm64.tgz
• agentos-darwin-x64.tgz
• agentos-linux-x64.tgz
• agentos-win32-x64.tgz
• matching .sha256 files

Run The App

pnpm dev

Open the URL printed by Next.js, typically:

http://localhost:3000

If OpenClaw is unavailable when the app starts, AgentOS shows an explicit unavailable/onboarding state and tells the operator what to repair before write actions can run.

Quality Checks

pnpm lint
pnpm typegen
pnpm typecheck
pnpm test
pnpm build
pnpm check:release
pnpm smoke:agentos-package

For a real local release rehearsal, run the clean-install smoke checklist in
docs/agentos-clean-install-smoke-checklist.md.

Operational Notes

• AgentOS is currently local-first. Several API routes spawn local processes, inspect transcript files, and mutate workspace directories.
• This makes the current implementation best suited for operator workstations or trusted environments, not serverless-only deployments.
• OpenClaw remains the runtime source of truth; AgentOS adds operator-facing control-plane state rather than a separate orchestration database.
• The OpenClaw integration is Gateway-first through a stable adapter/client boundary. CLI fallback remains intentional for install, recovery, gateway process control, and unsupported Gateway operations.
• The app is configured for standalone Next.js output via next.config.mjs.

Control-Plane APIs

Route	Method	Purpose
/api/snapshot	GET	Return the normalized AgentOS snapshot
/api/stream	GET	Stream snapshot updates over SSE
/api/diagnostics	GET	Return gateway diagnostics, capabilities, and presence
/api/mission	POST	Dispatch a mission to a real OpenClaw agent
/api/agents	GET, POST, PATCH, DELETE	Read and mutate agents
/api/workspaces	GET, POST, PATCH, DELETE	Read and mutate workspace projects
/api/runtimes/:runtimeId	GET	Load transcript-backed runtime output
/api/onboarding	POST	Install or start OpenClaw and verify readiness
/api/onboarding/models	POST	Discover models, refresh readiness, set a default model, or guide provider login
/api/update	POST	Run openclaw update and stream output
/api/gateway/control	POST	Start, stop, or restart the OpenClaw gateway
/api/planner	POST	Create a new workspace planning draft
/api/planner/:planId	GET, PUT	Load or save a planning draft
/api/planner/:planId/turn	POST	Process a planner conversation turn
/api/planner/:planId/simulate	POST	Simulate the planner team
/api/planner/:planId/deploy	POST	Deploy a planned workspace
/api/reset	POST	Preview or execute an AgentOS reset or full uninstall flow
/api/settings/gateway	PATCH	Update the OpenClaw gateway endpoint
/api/settings/workspace-root	PATCH	Update the default workspace root
/api/system/open-terminal	POST	Open a supported OpenClaw command in Terminal on macOS
/api/files/reveal	POST	Reveal a local file in Finder, Explorer, or the platform file manager

Local State And Persistence

AgentOS keeps most durable operational state close to the workspace and to OpenClaw itself.

• OpenClaw-backed runtime state comes from Gateway status, agent config, models, sessions, presence, Gateway events, and transcript files.
• Gateway event bridge state is stored under .mission-control/gateway-events/ and merged into runtime/task snapshots when available.
• AgentOS settings are stored under the legacy .mission-control/settings.json path.
• Planner drafts and planner runtime assets are stored under the legacy .mission-control/planner/ path.
• Planner deploys write workspace-specific planning artifacts under .openclaw/planner/, including blueprint.json and deploy-report.json.
• Browser convenience state such as theme, draft missions, recent prompts, and the last planner id is stored in localStorage.
• When OpenClaw is unavailable, AgentOS returns an explicit unavailable snapshot and keeps write actions blocked until setup is healthy.

Screens And Workflows Worth Exploring

• Create a workspace from scratch and inspect the generated scaffold files.
• Open the workspace wizard in advanced mode and move from company context to deploy.
• Create agents with different presets and heartbeat policies.
• Dispatch a mission, then inspect runtime output and created files from the inspector.
• Change the gateway endpoint or workspace root from settings and watch the live snapshot refresh.

Roadmap

This repository already shows the shape of a broader operating system for AI work.
Directionally, the next layer looks like this:

• Deeper company-level operations above individual project workspaces.
• Richer provisioning for channels, automations, hooks, and recurring operational loops.
• Stronger governance, permissions, approvals, and audit trails for multi-agent work.
• Better remote and multi-host control over OpenClaw-backed environments.
• More durable historical views for runtime analytics, operational memory, and handoff quality.

Contributing

Contributions are welcome.
If you want to extend the control plane, the planner, the workspace bootstrap flow, or the OpenClaw integration, open an issue or pull request.

Please keep contributions aligned with the current design principles:

• Keep the project developer-focused and operationally grounded.
• Prefer real OpenClaw-backed behavior over front-end-only mocks.
• Keep user-facing copy and documentation in English.
• Run pnpm lint, pnpm typecheck, and pnpm build before opening a PR.
• Prefer concise English commit messages; Conventional Commits are a good fit here.

License

MIT