The open-source, self-hosted alternative to Claude Managed Agents.

Run stateful, long-running AI agents on infrastructure you control.

Documentation · Quick start · API reference · Capabilities · Architecture

Mango provides the control plane and execution runtime for autonomous agent work. Define reusable Agents, run persistent Sessions, stream and steer them through an event API, and equip them with sandboxed tools, Files, Git repositories, Skills, Memory, credentials, schedules, and multi-agent delegation.

Why Mango

• Own the whole runtime. Keep the API, state, orchestration, credentials, model traffic, and execution within infrastructure and providers you choose.
• Keep accepted work durable. Sessions, events, interrupts, tool calls, and client-action waits survive API and worker restarts.
• Bring your infrastructure. Choose the model endpoint, object store, workers, and sandbox backend without handing the runtime to a hosted agent service.

Quick start

You need Docker with Compose and make. No external model credential is required for the local walkthrough.

git clone https://github.com/yanpgwang/mango.git
cd mango
export MANGO_API_KEY="${MANGO_API_KEY:-sk-mango-local-development}"
MANGO_MODEL_BASE_URL= MANGO_MODEL_API_KEY= MANGO_MODEL_ID= \
  docker compose -f deployments/local/compose.yaml up -d --build
make local-health

Follow the five-minute walkthrough to create an Environment, Agent, and Session, then send and stream your first message. The command above explicitly selects the deterministic offline model and supplies a development-only Mango API key unless you override it.

make local-up is a convenience command that automatically loads an existing ~/.config/mango/dev.env; it may enable a real model. Both paths use Docker: the worker creates a separate container for each Session that needs sandbox tools. The default image includes Python and the stack configures Files storage.

For real model tasks with Files and per-Session Docker sandboxes, follow Use a real model endpoint. The same stack keeps API admission and worker execution configured consistently.

Stop the Compose stack without deleting its data:

make local-down

To explore the Session and multi-agent APIs visually, try the terminal UI example:

cd examples/terminal-ui
go run ./cmd/mango-tui --demo

What you get

Area	Included
Agents and Sessions	Versioned Agent definitions, persistent Sessions, budgets, interrupts, and an event-based HTTP/SSE API
Tools and resources	Sandboxed file and shell tools, remote MCP, Files, Git repositories, custom Skills, Memory Stores, and encrypted credentials
Durable execution	Persisted event history, journaled tool calls, retries, park/resume, and restart recovery
Automation and delegation	Scheduled Deployments, Run history, signed durable Webhooks, persistent child Agents, and Advisor consultations
Execution environments	Docker by default, self-hosted worker leases, and Preview remote-sandbox adapters
Operator stack	PostgreSQL-authoritative state, Temporal workflows, S3-compatible objects, and NATS live previews

Important

Mango is alpha: its API is unstable and the project does not yet claim production readiness. Support varies by workflow and backend; review capabilities and limits before relying on a workflow. Docker shares the host kernel; the development stack is not a hardened boundary for hostile multi-tenant workloads.

Relationship to Claude Managed Agents

Mango began with resource and workflow ideas documented by Claude Managed Agents. It addresses the same class of stateful, long-running agent work as an independent open-source runtime designed for a self-hosted trust boundary. Mango is not an Anthropic product, does not proxy runtime behavior to a hosted agent service, and does not promise drop-in SDK or API compatibility. Mango owns its public API and roadmap; see Product direction for the design policy.

Architecture

flowchart LR
  Client --> API["Mango API"]
  API --> PG[("PostgreSQL")]
  API --> Objects[("S3-compatible storage")]
  API <-- "work lease + Session events" --> SelfHostedWorker["EnvironmentWorker"]
  SelfHostedWorker --> CustomerSandbox["Customer-hosted sandbox"]
  PG -- "durable outbox" --> Worker
  Worker <--> Temporal
  Worker --> Model["Model provider"]
  Worker --> Sandbox
  Worker -. "live previews" .-> NATS
  NATS -.-> API

Loading

PostgreSQL owns public state, event history, Memory contents and Versions, and File/Skill lifecycle intents. An S3-compatible store owns File bytes and immutable Skill archives. Temporal owns in-flight execution. NATS carries only ephemeral wakeups and previews; persisted events are always reconciled from PostgreSQL. A lost signal, process restart, or NATS outage cannot discard accepted work.

Read the architecture overview for the failure model, transactional outbox, tool journal, interrupt ordering, and sandbox lifecycle.

Documentation

The first-party SDKs provide Go, Python, and TypeScript/JavaScript clients for Mango's current HTTP API. Python and TypeScript use the package name mango-sdk. The SDKs remain alpha; see each package README for installation, including local source setup. No hosted agent service is required.

I want to…	Read
Run my first agent session	Getting started
Use Go, Python, or TypeScript	SDK guides and installation
Explore Mango in a terminal UI	Terminal UI example
Connect a real model endpoint	Use a real model endpoint
Choose an execution backend	Sandbox backends
Run a coordinator and child Agents	Multi-agent guide
Check an API operation	API reference
Understand supported behavior	Capabilities and limits
Plan a deployment	Deployment model

The complete documentation is also published at yanpgwang.github.io/mango.

Development

make verify       # lint, unit tests, race tests, and vet
make docs-check   # type-check and build the documentation site
make image-smoke  # build and smoke-test the container image

Default tests are offline. PostgreSQL, Temporal, NATS, MinIO, Docker, model, and remote-sandbox integrations have explicit opt-in suites. See the local stack guide and contribution guide.

Report vulnerabilities privately as described in SECURITY.md.

License

Mango is licensed under the Apache License 2.0.