mango

module

v0.1.0-alpha.4 Latest Latest Go to latest Published: Oct 18, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/yanpgwang/mango

Links

Open Source Insights

README ¶

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

Documentation · Quickstart · API reference · Examples

Define an Agent, start a Session, and send it work through an API. Mango runs the model-and-tool loop, persists the conversation, and coordinates execution and recovery. Build your application with Go, Python, TypeScript/JavaScript, or the HTTP API.

Why Mango?

Delegate execution. Configure instructions and tools, then let Mango drive the agent loop, manage context, and coordinate tool calls.
Own the infrastructure. Self-host the API, orchestration, state, and tool workers. The first-party Docker launcher runs shell and file operations on your infrastructure; model calls use your configured endpoint.
Keep work running. Persist accepted input, conversation history, and action waits across API and orchestration-worker restarts.
Stay in control. Stream responses, send follow-ups, interrupt a turn, or wait for a person or your application to return a tool result.
Build beyond one agent. Coordinate persistent specialists, reuse Skills and Memory, schedule Sessions, and subscribe to lifecycle Webhooks.

[!IMPORTANT] Mango is alpha. APIs may change, and production deployment is not yet supported. See capabilities and limits for the supported scope of each workflow.

Quickstart

You need Git, Docker with Compose, and make. Start the local stack with its built-in offline model; no model credentials are needed:

git clone https://github.com/yanpgwang/mango.git
cd mango
export 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

With curl and jq installed, run a complete first Session:

bash examples/sdk-quickstart.sh

The example creates an Environment, Agent, and Session, sends a message, reads the persisted reply, and cleans up its resources. Look for Quickstart completed. This is a text-only walkthrough; running shell or file tools requires a separate Environment worker. The local key above is for development only.

Prefer an SDK? The Quickstart walks through the same flow in TypeScript, Python, Go, and HTTP. The current resource-based SDKs must be installed from source; published alpha 1 packages use an earlier interface. Follow the SDK installation guide.

Stop the stack while keeping its data:

make local-down

To follow an existing Session, send messages, and answer approvals from a terminal, see mango sessions connect.

Explore Mango

I want to…	Start here
Understand Agents, Sessions, and workers	Core concepts
Connect a model endpoint	Model configuration
Run sandboxed shell and file tools	Docker worker guide
Add human input or coordinate a team	Runnable examples
Integrate an API operation	API reference
Understand deployment and recovery	Deployment · Architecture

Mango is an independent project, unaffiliated with Anthropic. Claude Managed Agents is a design reference; Mango owns its API and does not require or proxy a hosted agent service. See design provenance for adopted concepts and intentional differences.

Contributing

Bug reports, documentation fixes, and focused pull requests are welcome. Start with CONTRIBUTING.md for setup and the relevant tests.

make verify       # lint, unit tests, race tests, and vet
make docs-check   # check and build the documentation site

Report vulnerabilities privately through the process in SECURITY.md.

License

Apache License 2.0.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
mango command
mango-worker command mango-worker is the standalone worker-side runtime for self_hosted Mango Environments.	mango-worker is the standalone worker-side runtime for self_hosted Mango Environments.
examples
coding-agent command Command coding-agent fixes a small Python project using Mango's public SDK and the standalone Docker supervisor.	Command coding-agent fixes a small Python project using Mango's public SDK and the standalone Docker supervisor.
hitl-gate command Command hitl-gate is a standalone Mango SDK application, not a runtime runner.	Command hitl-gate is a standalone Mango SDK application, not a runtime runner.
mongodb-query command Command mongodb-query asks an agent to query MongoDB from a Docker worker.	Command mongodb-query asks an agent to query MongoDB from a Docker worker.
multi-agent-team command Command multi-agent-team runs a real-model coordinator, specialist, Advisor, and persistent follow-up workflow against Mango's public HTTP API.	Command multi-agent-team runs a real-model coordinator, specialist, Advisor, and persistent follow-up workflow against Mango's public HTTP API.
internal
agentruntime
agentruntime/tools Package tools provides the built-in tool executors that an agent runtime runs inside a sandbox, plus the model-facing input schemas that describe them to the model.	Package tools provides the built-in tool executors that an agent runtime runs inside a sandbox, plus the model-facing input schemas that describe them to the model.
app
blob Package blob implements durable byte storage for public File resources.	Package blob implements durable byte storage for public File resources.
buildinfo Package buildinfo identifies a runtime binary without connecting to services.	Package buildinfo identifies a runtime binary without connecting to services.
controlplane Package controlplane wires the public HTTP resource semantics to the PostgreSQL ledger and Temporal admission boundary.	Package controlplane wires the public HTTP resource semantics to the PostgreSQL ledger and Temporal admission boundary.
credentialruntime Package credentialruntime defines transport-neutral contracts shared by the Vault application service and the outbound OAuth and MCP adapters.	Package credentialruntime defines transport-neutral contracts shared by the Vault application service and the outbound OAuth and MCP adapters.
domain
httpapi
httpegress Package httpegress provides HTTP clients that enforce the public-network boundary for tenant-configured outbound endpoints.	Package httpegress provides HTTP clients that enforce the public-network boundary for tenant-configured outbound endpoints.
live Package live provides the ephemeral real-time side of the event API.	Package live provides the ephemeral real-time side of the event API.
mcpclient Package mcpclient owns remote MCP discovery and invocation.	Package mcpclient owns remote MCP discovery and invocation.
model Package model defines the inference client the agent core calls.	Package model defines the inference client the agent core calls.
oauthclient Package oauthclient implements the OAuth refresh-token exchange used by Vault-backed MCP credentials.	Package oauthclient implements the OAuth refresh-token exchange used by Vault-backed MCP credentials.
permission Package permission evaluates proposed invocations.	Package permission evaluates proposed invocations.
pg Package pg provides the authoritative control-plane persistence: a pgx pool, embedded goose migrations, and stores built on sqlc-generated queries.	Package pg provides the authoritative control-plane persistence: a pgx pool, embedded goose migrations, and stores built on sqlc-generated queries.
pg/pgstore
secretcrypto Package secretcrypto provides authenticated encryption for control-plane secrets.	Package secretcrypto provides authenticated encryption for control-plane secrets.
selfhosted Package selfhosted implements operator-side launchers for Mango's self_hosted Environment Work protocol.	Package selfhosted implements operator-side launchers for Mango's self_hosted Environment Work protocol.
sessionconnect Package sessionconnect implements the operator CLI over Mango's native SDK.	Package sessionconnect implements the operator CLI over Mango's native SDK.
temporal Package temporal implements the platform-spine's durable session orchestration: a SessionWorkflow keyed by the public session ID, granular model/tool Activities behind a Workflow-owned agent loop, idempotent PostgreSQL completion, and the outbox relay that wakes the workflow with Signal-With-Start.	Package temporal implements the platform-spine's durable session orchestration: a SessionWorkflow keyed by the public session ID, granular model/tool Activities behind a Workflow-owned agent loop, idempotent PostgreSQL completion, and the outbox relay that wakes the workflow with Signal-With-Start.
testutil/dockertest Package dockertest contains opt-in Docker infrastructure for repository tests.	Package dockertest contains opt-in Docker infrastructure for repository tests.
workspace Package workspace defines Mango's only tenant boundary.	Package workspace defines Mango's only tenant boundary.
scripts
kubernetes/model command Command model is an explicitly simulated Messages endpoint for isolated Kubernetes acceptance.	Command model is an explicitly simulated Messages endpoint for isolated Kubernetes acceptance.
sdk-contract command Command sdk-contract exports Mango's OpenAPI document for SDK generators.	Command sdk-contract exports Mango's OpenAPI document for SDK generators.
sdk
go module