MultiAgentOS

Local-first, GitHub-native Agent Execution Runtime

Build, inspect, patch, test, and operate real software projects through an AI-native execution boundary.

MultiAgentOS connects an AI client to a real project workspace while keeping filesystem, patch, process, Git, and verification authority inside the Agent Execution Runtime.

Why MultiAgentOS?

AI clients provide reasoning, intent, plans, and results.

MultiAgentOS provides the execution boundary.

flowchart TB
    CLIENT["AI Client"] --> MCP["MCP"]
    MCP --> RUNTIME["Agent Execution Runtime"]
    RUNTIME --> FS["Filesystem"]
    RUNTIME --> PATCH["Patch"]
    RUNTIME --> PROCESS["Process"]
    RUNTIME --> GIT["Git"]
    FS --> PROJECT["Real Project"]
    PATCH --> PROJECT
    PROCESS --> PROJECT
    GIT --> PROJECT
    PROJECT --> GH["GitHub Repository"]

This separation makes local project execution explicit, inspectable, and policy-controlled instead of giving an AI client unrestricted operating-system access.

Core Capabilities

Write and process capabilities are explicit opt-ins. The default MCP surface is read-only.

Architecture

Local-first execution

flowchart TB
    CLIENT["AI Client"] --> MCP["MCP"]
    MCP --> RUNTIME["Agent Execution Runtime"]

    RUNTIME --> FS["Filesystem"]
    RUNTIME --> PATCH["Patch"]
    RUNTIME --> PROCESS["Process / Tests"]
    RUNTIME --> GIT["Git"]

    FS --> PROJECT["Local Project"]
    PATCH --> PROJECT
    PROCESS --> PROJECT
    GIT --> PROJECT

    PROJECT --> GH["GitHub Repository"]

The local MCP server remains on loopback. The AI client does not receive unrestricted operating-system access; execution is mediated by the runtime policy.

Multi-agent execution

flowchart LR
    REQUEST["Request"] --> ORCH["Orchestrator"]
    ORCH --> WORKFLOW["MultiAgentWorkflow"]

    WORKFLOW --> DEV["Developer"]
    WORKFLOW --> TEST["Tester"]
    WORKFLOW --> REVIEW["Reviewer"]

    REVIEW --> DECISION{"Review passed?"}
    DECISION -->|No| REWORK["Rework"]
    REWORK --> DEV
    DECISION -->|Yes| VERIFY["Verification"]

    VERIFY --> RUNTIME["Agent Execution Runtime"]

Orchestrator.run_workflow() is the higher-level orchestration entry point. MultiAgentWorkflow owns stage, handoff, review, and rework semantics.

The runtime remains the authority for permissions and execution.

Governance contracts

MultiAgentOS keeps execution governance inside its own provider-neutral runtime contracts.

flowchart TB
    WU["WorkUnit"] --> SCOPE["Scope Lock"]
    WU --> ROLES["Execution roles"]
    WU --> ART["Artifacts"]
    WU --> EVID["Evidence"]
    WU --> APPROVAL["Human approval"]
    WU --> HOLD["HOLD safety"]

    SCOPE --> RUNTIME["MultiAgentOS Runtime"]
    ROLES --> RUNTIME
    ART --> RUNTIME
    EVID --> RUNTIME
    APPROVAL --> RUNTIME
    HOLD --> RUNTIME

    RUNTIME --> TOOLS["MCP / Filesystem / Process / Git / GitHub"]

These governance contracts are native to MultiAgentOS; they are not dependent on another repository or project-specific Agent OS.

Agent taxonomy and specialist routing

MultiAgentOS separates Governance / Execution from platform-oriented specialist agents.

flowchart TB
    TASK["Task"]

    TASK --> GOV["Governance / Execution"]
    TASK --> RESEARCH["Research"]
    TASK --> DEVELOPMENT["Development"]
    TASK --> UI["UI"]

    GOV --> FILE["File Picker"]
    GOV --> PLAN["Planner"]
    GOV --> EDIT["Editor"]
    GOV --> EXEC["Executor"]
    GOV --> REVIEW["Reviewer"]

    RESEARCH --> DEV_R["Development Research"]
    RESEARCH --> UI_R["UI Research"]

    DEV_R --> REACT_R["React"]
    DEV_R --> RN_R["React Native"]
    DEV_R --> ANDROID_R["Android"]
    DEV_R --> IOS_R["iOS"]

    UI_R --> WEB_R["Web UI / React"]
    UI_R --> RN_UI_R["React Native UI"]
    UI_R --> ANDROID_UI_R["Android UI"]
    UI_R --> IOS_UI_R["iOS UI"]

    DEVELOPMENT --> REACT_D["React Developer"]
    DEVELOPMENT --> RN_D["React Native Developer"]
    DEVELOPMENT --> ANDROID_D["Android Developer"]
    DEVELOPMENT --> IOS_D["iOS Developer"]

    UI --> WEB["Web"]
    UI --> CROSS["Cross-platform"]
    UI --> NATIVE["Native"]
    NATIVE --> ANDROID["Android"]
    NATIVE --> IOS["iOS"]

A platform-aware development task can therefore run current platform research before implementation:

flowchart LR
    TASK["Platform Development"] --> PLAN["Planner"]
    PLAN --> RESEARCH["Development Research"]
    RESEARCH --> DEV["Platform Developer"]
    DEV --> EDIT["Editor"]
    EDIT --> EXEC["Executor"]
    EXEC --> REVIEW["Reviewer"]

UI work similarly runs UI research before implementation and uses Browser Agent only where browser validation is relevant.

See Agent Taxonomy and Routing and Agent Catalog.

GitHub + Local Project

MultiAgentOS treats the remote repository and the local working tree as complementary development surfaces.

flowchart TB
    CLIENT["AI Client"]

    CLIENT --> GH["GitHub Repository"]
    CLIENT --> MCP["Local MCP"]

    MCP --> RUNTIME["Agent Execution Runtime"]
    RUNTIME --> PROJECT["Local Project"]

The GitHub path provides durable repository state.

The local MCP path provides controlled access to the actual working tree.

These are separate capabilities and can be used independently.

ChatGPT Web in the Verified Setup

The current development environment has verified the following client boundary:

This is a compatibility record for the verified environment, not a universal guarantee for every ChatGPT account, plan, or future client build.

Execution boundary: Process/shell execution is not currently part of the verified ChatGPT Free client path. The runtime contains process-capability infrastructure, but README support claims are limited to capabilities actually exposed and verified through the target client path.

The cost-free local workflow does not depend on Secure MCP Tunnel:

flowchart TB
    WEB["ChatGPT Web"]

    WEB -->|GitHub connection| GH["GitHub Repository"]
    WEB -->|Local MCP| MCP["127.0.0.1:8000/mcp"]
    MCP --> PROJECT["Local Project"]

Secure MCP Tunnel

Secure MCP Tunnel is an optional remote connectivity layer for supported clients that need to reach a private local MCP server.

flowchart TB
    CLIENT["Supported Remote Client"]
    TUNNEL["OpenAI Secure MCP Tunnel"]
    TC["tunnel-client"]
    MCP["MultiAgentOS MCP"]
    RUNTIME["Agent Execution Runtime"]
    PROJECT["Local Project"]

    CLIENT --> TUNNEL
    TUNNEL --> TC
    TC --> MCP
    MCP --> RUNTIME
    RUNTIME --> PROJECT

The local MCP server can remain loopback-only. The tunnel client establishes the outbound connection.

Important boundary

A healthy tunnel proves that the tunnel infrastructure is connected. It does not by itself prove that a particular ChatGPT account or plan can invoke every MCP capability.

For the current cost-free baseline:

Do not treat the optional hosted tunnel path as a prerequisite for local development.

See Secure MCP Tunnel Setup.

Project-Scoped Runtime

Multiple projects can run independently.

flowchart TB
    A["Project A"]
    A --> A_MCP["MCP Service"]
    A --> A_RUNTIME["Runtime"]
    A --> A_TUNNEL["Tunnel (optional)"]
    A --> A_LOGS["Logs"]
    A --> A_PERM["Permissions"]

    B["Project B"]
    B --> B_MCP["MCP Service"]
    B --> B_RUNTIME["Runtime"]
    B --> B_TUNNEL["Tunnel (optional)"]
    B --> B_LOGS["Logs"]
    B --> B_PERM["Permissions"]

Each managed project receives its own service identity derived from its resolved project path.

Example:

multiagentos mcp install \
  --path /absolute/path/to/project1 \
  --port 8000 \
  --allow-write

multiagentos mcp install \
  --path /absolute/path/to/project2 \
  --port 8001 \
  --allow-write

Inspect or remove a project-scoped service:

multiagentos mcp status --path /absolute/path/to/project1
multiagentos mcp uninstall --path /absolute/path/to/project1

Supported OS-native lifecycle management includes:

• macOS: per-user launchd
• Windows: per-user Task Scheduler

Cost-Free Development Baseline

The core user-facing path is:

ChatGPT Free text chat
        |
        v
MultiAgentOS
        |
        v
Local MCP
        |
        v
Project state / source changes / verification

Cost-Free policy: development must be possible without an OpenAI API key by using ChatGPT Free text chat as the AI engine and MultiAgentOS Local MCP as the controlled execution boundary.

This policy does not claim that every ChatGPT feature is unlimited. It defines the intended AI-engine path for ordinary text-based development work.

The baseline is designed around:

flowchart TB
    INSTALL["Install MultiAgentOS"]
    INIT["Initialize project"]
    MCP["Agent Execution Runtime MCP"]
    CLIENT["AI Client"]

    INSTALL --> INIT --> MCP --> CLIENT

    CLIENT --> READ["READ"]
    CLIENT --> PATCH["PATCH"]
    CLIENT --> TEST["TEST"]
    CLIENT --> VERIFY["VERIFY"]

    READ --> GH["GitHub"]
    PATCH --> GH
    TEST --> GH
    VERIFY --> GH

“Cost-Free” describes the MultiAgentOS runtime architecture. It does not mean that an AI product has unlimited usage or that every optional AI service is free.

Paid AI providers remain optional.

See Cost-Free Development Baseline.

Quick Start

Install

For the Streamable HTTP MCP server:

python3 -m pip install "multiagentos[mcp-http]"

No OpenAI API key is required for the local runtime.

Initialize a project

flowchart LR
    INSTALL["Install MultiAgentOS"] --> INIT["multiagentos init ."]
    INIT --> PROFILE["Project profile"]
    INIT --> CONFIG[".multiagentos"]
    INIT --> AGENTS["AGENTS.md"]
    CONFIG --> MCP["Project MCP"]
    MCP --> RUNTIME["Agent Execution Runtime"]
    RUNTIME --> PROJECT["Real project"]

cd your-project
multiagentos init . --component all
multiagentos status .

See Project Installation for the complete bootstrap contract.

Run a task

multiagentos run \
  --path . \
  --objective "run tests" \
  -- python -m unittest discover -s tests -v

Start a Chat Agent session

multiagentos chat \
  --path . \
  --objective "inspect the current project"

Start local MCP

Read-only:

multiagentos mcp serve-http --path .

Read/write:

multiagentos mcp serve-http \
  --path . \
  --allow-write

The default endpoint is:

http://127.0.0.1:8000/mcp

Install as a persistent macOS service

multiagentos mcp install --path . --allow-write
multiagentos mcp status --path .

The service is managed by launchd and can survive login/reboot.

Configuration

Project configuration lives under:

.multiagentos/
├── components.json
├── execution.json
├── chat.json
├── agents.json
└── state/

Credentials and provider API keys are not written into project configuration.

Verification

MultiAgentOS v0.4.3 release verification record

The following results are the recorded verification evidence for the v0.4.3 release:

• 309 tests passed
• 3 tests skipped on macOS
• macOS managed MCP service verified after reboot/login
• Project-scoped Secure MCP Tunnel lifecycle verified
• Tunnel-client control-plane polling verified
• Python wheel and source distribution build verified
• Native release artifacts published
• Local Agent Execution Runtime filesystem READ / WRITE verified
• patch.apply verified with filesystem readback
• GitHub-connected development path verified

These bullets are a release verification record, not a claim that the same test count has been freshly executed for every later main commit. Current main changes are validated by the repository's GitHub Actions workflows.

Verification boundary

The repository deliberately distinguishes:

flowchart TB
    LOCAL["Local Runtime Verification"]
    LOCAL --> MCP["MCP"]
    LOCAL --> FS["Filesystem"]
    LOCAL --> PATCH["Patch"]
    LOCAL --> PROCESS["Process"]
    LOCAL --> GH["GitHub"]

    VERIFIED["Verified"]
    MCP --> VERIFIED
    FS --> VERIFIED
    PATCH --> VERIFIED
    PROCESS --> VERIFIED
    GH --> VERIFIED

    TUNNEL["Optional Hosted Tunnel"]
    TUNNEL --> LIFECYCLE["Tunnel lifecycle"]
    TUNNEL --> POLL["Control-plane polling"]
    TUNNEL --> REMOTE["Remote client capability"]

    DEP["Environment / plan dependent"]
    LIFECYCLE --> DEP
    POLL --> DEP
    REMOTE --> DEP

This prevents a healthy tunnel from being incorrectly reported as proof of a hosted client-side MCP tool invocation.

Security and Permission Model

MultiAgentOS keeps execution authority behind an explicit runtime boundary.

flowchart TB
    INTENT["AI Intent"]
    REQUEST["MCP Tool Request"]
    POLICY["Execution Policy"]

    INTENT --> REQUEST --> POLICY

    POLICY --> READ["filesystem.read"]
    POLICY --> WRITE["filesystem.write"]
    POLICY --> PATCH["patch.apply"]
    POLICY --> PROCESS["process / shell"]

    READ --> PROJECT["Real Project"]
    WRITE --> PROJECT
    PATCH --> PROJECT
    PROCESS --> PROJECT

Write and process capabilities require explicit opt-in.

For the tunnel path, keep credentials separated:

CONTROL_PLANE_TUNNEL_ID
    → identifies the tunnel

CONTROL_PLANE_API_KEY
    → runtime credential used by tunnel-client

OPENAI_ADMIN_KEY
    → tunnel administration only

Do not place an administration key in a long-lived runtime configuration.

Documentation

• Getting Started
• Project Installation
• Cost-Free Development Baseline
• ChatGPT Client Capability Matrix
• Agent Execution Runtime Connection Guide
• Secure MCP Tunnel Setup
• macOS MCP Service
• macOS Tunnel Service
• Agent Execution Runtime GitHub Connection
• Architecture Decisions
• Agent Plugin Marketplace

The English README is the canonical technical overview. Localized READMEs should preserve the same architecture, terminology, and cost-free baseline.

한국어

License

See LICENSE.