managed-agent-platform

managed-agent-platform

An open-source, self-hostable platform for long-horizon AI agents, written in Go.

Run the whole thing on-prem or in your own VPC — your data and your compute never leave your boundary.

Status: v0.5.0 — the v1 loop is complete; agents reach MCP servers, the control plane authenticates people, a coordinator agent's roster runs as concurrent session threads, a session mounts versioned memory stores it reads and writes back, a deployment fires an agent on a cron schedule with its run history readable over the wire, and a dream consolidates one of those memory stores over past session transcripts. A v* tag publishes container images and the Helm chart to GHCR, and worker binaries with clamped release notes to the GitHub Release (docs/RELEASING.md).

What runs today, end to end:

• The core loop — the wire-compatible control-plane API over an append-only session event log with SSE streaming, config-driven model providers (Anthropic-protocol and OpenAI-compatible), and the brain orchestration loop.
• Tools in sandboxes — the complete agent_toolset_20260401, executing in per-session Docker or Kubernetes sandboxes under permission policies with human-in-the-loop approval. web_search and web_fetch are the deliberate exception: they run in the platform executor behind config-driven backends, on both deployment modes, with no sandbox involved. A cloud environment's config.packages is installed into the sandbox — the six managers the reference names, in its alphabetical order — before the session's first tool runs.
• Your own compute — BYOC workers run a self-hosted session's tools, with dead-worker recovery and a single OTel trace across the process boundary.
• Sandbox lifecycle — an executor-resident reaper destroys the sandboxes of deleted, archived and terminated cloud sessions, and checkpoints an idle one's workspace to object storage, restoring it intact when the next message arrives. A self_hosted session's sandbox belongs to its BYOC worker and is never touched.
• Session resources — skills, files and GitHub repositories mount into a session; each mounted file is the session's own copy, with its own file_id and the upload's bytes, so deleting the upload leaves the session's mount in place; repositories are cloned platform-side, so the token never enters the container the agent controls.
• Memory stores — a workspace-scoped, versioned collection of text documents attaches through resources[], mounts at /mnt/memory/<slug>, and is read and written with the ordinary file tools; every write becomes an attributed, immutable version, and the store stays in sync across the sessions that share it, cloud and BYOC alike — the BYOC worker reconciling over the wire with the per-item sessions token its work items carry.
• Dreams — a dream consolidates one memory store over 1–100 past session transcripts. The control plane renders each transcript with secrets redacted and its size capped, mounts them beside a clone of the store, and runs a pipeline session under the model the request names — so what the job rewrites is the clone, which you review and keep or discard, and the store you fed it is untouched. The five /v1/dreams routes are the reference's, ant beta:dreams drives them, and the pipeline behind them runs four stages — orient over the transcripts, digest them through one delegated thread per batch, merge the digests into the store, then rewrite its index and report. Asking for update_existing instead consolidates the store you named in place, at most one such job per store at a time; that session runs with no shell, so it can create and change memories but never delete one, and a memory it retires is left as a tombstone naming its successor for you to remove.
• Outcomes — a text or file rubric is graded each work cycle, and revision feedback runs up to max_iterations.
• Session deliverables — whatever the agent writes under /mnt/session/outputs/ in a cloud session is harvested into the Files API, with or without an outcome, and lists and downloads through GET /v1/files?scope_id=<session> — the unfiltered list leaves a session's files out. Any of five brain settlement folds triggers a harvest — a plain end_turn, a retries-exhausted failure, a confirmation gate, a delegated park, and a spent delegation budget — not literally every idle: the two folds that end an outcome cycle already harvested the same tree, and the two idle folds the API makes (a user.interrupt, a session's last-thread archive) are tracked separately by #586. A self_hosted session never harvests, because the platform cannot reach a BYOC sandbox. Deleting the session takes what it harvested with it, rows and bytes both; archiving keeps them, and a file you uploaded through the Files API is untouched by either.
• Vaults and egress — /v1/vaults holds cipher-sealed, write-only credentials that a session attaches at create time; a limited environment's traffic leaves through a per-session egress gate that enforces allowed_hosts — widened only by the two flags beside it, which open the agent's declared MCP endpoints and a curated thirty-host set of package-registry, source-forge and container-registry hosts (host reach is what the recording establishes; whole clones and image pulls are not) — and substitutes those credentials on the way out, so the sandbox only ever holds an opaque placeholder.
• MCP servers — declared per agent, discovered, offered to the model and answered under human confirmation by default, with vault credentials matched and expiring OAuth tokens refreshed at the dial.
• Multi-agent teams — a coordinator agent's multiagent roster runs as concurrent session threads on one shared sandbox, each thread with its own agent, event log, status and stream, matching the reference's sthr_ thread resource and its /threads routes. The coordinator spawns its agents, messages them, lists them and waits on them; they report back, and the session's status is a fold over its threads'. Cloud and BYOC alike — the customer-run worker stays thread-unaware, because the session view it already reads carries the child calls it must run.
• Scheduled deployments — a deployment binds an agent to an environment, credentials, resources and initial events; POST /run fires it by hand, and an optional 5-field POSIX cron schedule fires it on the clock — at most one run per occurrence across every control-plane replica, a bounded catch-up after downtime, and a classified fire failure recording an error-bearing run that auto-pauses the schedule (an unclassified one rolls back whole and retries — docs/DIVERGENCES.md registers the trade). /v1/deployment_runs reads the history back.
• Human authentication — the control plane is a vendor-SDK-free OIDC relying party (Casdoor bundled as an optional hardened default, plus a trusted-proxy mode where the cloud terminates auth). It resolves each request to a principal whose claims map to one of admin · developer · viewer, and refuses one that maps to none — identity is default-deny.

Machine credentials keep their own lane ahead of identity: x-api-key, and every environment key this platform minted, behave identically whether identity is configured or not, which is why the real ant CLI — ant beta:worker included — drives every machine flow unchanged. (The one exception is a grandfathered key whose operator-chosen value happens to be JWT-shaped; it is refused fail-closed rather than over-authorized, and docs/self-hosted-security.md §6 says to reissue it before enabling SSO.) Human login is the one thing it cannot: this platform deliberately serves no POST /v1/oauth/token, so people sign in to their own IdP out of band (docs/DIVERGENCES.md registers the divergence). Deploy locally with docker-compose or to Kubernetes with the Helm chart; CHANGELOG.md is what landed when, and the issue tracker is what's next.

Why

Most agent platforms are SaaS: your source code, your prompts, and your tool output all flow through someone else's infrastructure. For enterprises with data-residency, compliance, or air-gap requirements, that's a non-starter.

This project is that platform, self-hosted:

• Bring your own model. Providers are config-driven (protocol · model · base_url · api_key). The Anthropic-protocol provider works against any endpoint speaking Anthropic Messages — a gateway, a proxy, or a self-hosted model — and an OpenAI-compatible provider covers OpenAI, vLLM, and most internal gateways. Nothing hard-codes a vendor endpoint. Explicit model.effort is passed to the chosen endpoint (output_config.effort for Anthropic, reasoning_effort for OpenAI-compatible routes); omitted effort uses its default, and the endpoint decides model-specific support.
• Bring your own compute. Sandboxes run on Docker or Kubernetes under your control. Customer-run workers pull work from the platform, so no inbound network access is required into your environment.
• Observability is built in. OpenTelemetry traces, metrics, and logs over standard OTLP — point it at your existing Jaeger/Tempo/Prometheus stack.

Relationship to Claude Managed Agents

We take Anthropic's Claude Managed Agents as our reference implementation: we adopt its domain model and keep our public REST API wire-compatible with it, so the real ant CLI and the Anthropic SDKs can drive this server unchanged.

This is a deliberate compatibility and design choice, not an attempt to reproduce that product. Where our goals — self-hosting, pluggable model backends, first-class OTel — call for something different, we diverge on purpose and document why.

model.inference_geo is preserved as protocol-compatible configuration metadata. It does not change provider requests or routing: inference geography is determined by your deployment and upstream configuration. Its echoed value is not a geographic execution guarantee; the platform does not implement workspace geo policies or regional enforcement. See DIVERGENCES.

Architecture

An agent is three independently-swappable pieces:

Execution is fully asynchronous through the event log and a work queue. The brain runs no agent tool in-process: it emits agent.tool_use, an executor pulls that work, runs it inside a sandbox, and posts the result back; the brain wakes and continues. (Multi-agent delegation is the one exception — those tools touch no sandbox and are answered where the turn commits.) Platform-managed sandboxes and customer-run (BYOC) workers are the same pull protocol at two deployment points.

Two security invariants, adopted from the reference design:

1. Credentials never reach the sandbox. Repos are cloned with a token the sandbox never sees; tool credentials are injected at egress.
2. A session is not a context window. The harness may replay, slice, or rewind the event log before feeding the model, so context strategy is never baked into an irreversible compaction.

Self-hosting means you own the infrastructure these run on. The self-hosted shared-responsibility model draws the line: what the platform enforces in code (credential isolation, scoped auth, fail-closed egress, and the sandbox's own cgroup limits and capability drops — on by default) versus what you configure (the sandbox image, egress policy for non-limited environments, a hardened container runtime, environment-key rotation).

For Google Cloud specifically, docs/deploy-gcp.md is the deployment guide — GKE with Cloud SQL, Cloud Storage and Cloud KMS, the settings that are required rather than recommended (podPidsLimit, TLS in front of the control plane), sandbox-pool sizing from measured numbers, the gVisor boundary, and the teardown step terraform destroy does not do. The Terraform it describes is deploy/gcp/. Both deployment shapes have been stood up and accepted on real GKE — the bundled-services one and the Google-managed one, the latter with the platform's database role held outside cloudsqlsuperuser and every backing service reached with the deployment's own credential rather than the operator's; the acceptance records are in docs/HISTORY.md. Production shape, not a readiness verdict: the guide names what it does not establish.

Roadmap

v1 delivered the core loop: create agent → create environment → create session → send a message → the model calls a tool → an executor runs it in a sandbox → results stream back over SSE → a human approves a gated tool → the session goes idle.

Progress is tracked in:

• CHANGELOG.md — landed work, newest first; new changes accumulate as fragments in changelog.d/ until a release folds them in, and released sections archive to docs/changelog/ behind index stubs post-release.
• GitHub issues — the backlog and open questions.
• STATE.md — the active work and its task progress. The as-built system is docs/ARCHITECTURE.md; acceptance and decision records are docs/HISTORY.md (older months archive to docs/history/).

Deferred past v1 — seams reserved, not implemented, each tracked as an issue. The canonical list is the open issues whose titles carry the (post-v1) marker (gh issue list --state open --limit 100 --search "post-v1 in:title", which also returns the occasional issue that merely mentions the phrase); the notes below single out what most often surprises a reader, and are neither the whole of that set nor confined to it. Vaults, skills, files, repository mounting, memory stores and scheduled deployments were on this list and have since landed; what remains includes:

• The multi-tenant half of RBAC and SSO (#56, which stays open for it). Single-tenant SSO and the three-role matrix are done.
• Repository materialization on BYOC compute (#322): a self_hosted session accepts a github_repository resource and mounts nothing, without being told otherwise.
• BYOC gate delivery (#165) and credential substitution inside TLS (#166) — until #166, an in-sandbox HTTPS request keeps its vault placeholders rather than having them substituted at egress.

Development

Requires Go 1.26+ and Docker. go.mod's toolchain line names the Go release CI and the release images build with; a local go older than it downloads and runs that release, while a newer one keeps itself, as does any go under GOTOOLCHAIN=local. The storage and API contract tests start their own disposable Postgres containers, and the sandbox, shell, toolset, and executor tests start a disposable debian:stable-slim container (the toolset's search tests start a postgres:16-alpine one too, and one built from bash:3.2). The fixtures that drive the daemon through the docker CLI rather than its HTTP API — the storage, API, sandbox and toolset ones — need that binary on PATH as well. The Kubernetes sandbox provider's contract test additionally needs a cluster — a local kind cluster works, and CI provisions one. A missing daemon, binary or cluster is a hard test failure, not a skip, so the coverage gate cannot be hollowed out.

The executor and the worker embed the static ripgrep their grep tool runs in a sandbox. It is fetched, not committed: make ripgrep downloads the pinned release archives from GitHub and checks their digests, and make test, make eval, the release targets and the Dockerfile run it first. A plain go build or go run without it still compiles, into an executor and a worker that log a warning at startup and whose grep reports that they carry no ripgrep.

make build                 # build (go build ./...)
make ripgrep               # fetch the pinned static ripgrep the executor and worker embed
make test                  # unit + contract tests (go test -count=1, with coverage profile)
make vet fmt-check         # lint
make verify                # the whole Go gate (CI additionally runs its helm, terraform and compose jobs)
make eval                  # RUN_EVALS=1: the live end-to-end eval suite (real model + sandboxes)
make registry-check        # ask GitHub about docs/DIVERGENCES.md's pointers: live trackers open, provenance known

Tests come in tiers. The first two run on every PR and call no model; the rest drive a real endpoint, so they cost money and are opt-in by an environment variable — a configured .env supplies the endpoint, never the consent to spend it on. Once opted in, missing configuration fails rather than skipping: a safety net that quietly skips itself when its credentials rot is not a safety net.

Configure the dotenv-loading tiers once in a gitignored repo-root .env: the endpoint itself — MODEL_PROTOCOL (anthropic|openai), MODEL_BASE_URL, MODEL_API_KEY, MODEL_ID — and the per-tier names the table above spells out for the model, web, MCP, KMS, Cloud Storage and eval tiers. The environment wins over the file. Live acceptance is the exception: RUN_LIVE_ACCEPTANCE_TESTS and its ACCEPTANCE_* settings are read from the process environment only and are never loaded from .env, because that tier drives an externally running stack rather than this checkout's. Never commit real credentials. The eval fixture is the one entry with a requirement of its own: EVAL_GITHUB_REPO_URL must name a private repository holding a PASSPHRASE.txt, and EVAL_GITHUB_REPO_TOKEN a fine-grained, single-repository, Contents: Read-only token for it. That trial carries no per-trial nonce, so the repository's privacy is what keeps the answer secret.

Those are test settings. What a running deployment reads is separate: BLOB_BACKEND picks the object-storage backend — unset or s3 for any S3-compatible endpoint (BLOB_ENDPOINT and its BLOB_* companions), gcs for Google Cloud Storage natively, which takes BLOB_BUCKET alone and authenticates with Application Default Credentials, so there is no key to distribute.

Run the platform locally with the docker-compose stack — controlplane, brain, and executor against a bundled Postgres, object store (PGSTY Silo, a MinIO fork), and OpenBao (and an optional Jaeger):

cd deploy/compose
cp .env.example .env          # set CONTROLPLANE_API_KEY
docker compose up --build     # control plane on http://localhost:8080 (loopback)

Then drive it with the real CLI: ANTHROPIC_API_KEY=<key> ant --base-url http://localhost:8080 beta:agents list (management commands take --base-url explicitly; they ignore ANTHROPIC_BASE_URL, which only the worker/auth subcommands honor). The stack idles until you point the brain at your model endpoint (copy model-providers.example.json and set MODEL_PROVIDERS_FILE). See deploy/compose/README.md for details; production deploys use the Helm chart — from v0.2.0 onward installable straight from the registry (helm install map oci://ghcr.io/opensdlc-dev/charts/managed-agent-platform --version <X.Y.Z> ...), with prebuilt worker binaries attached to each GitHub Release. Upgrade BYOC workers together with the platform: the brain offers the model the tools of its release and a worker runs those of its own, and the work protocol, the reference's, carries no worker version, so nothing refuses or flags a mismatch.

Contributions are welcome. Please read CLAUDE.md first — it documents the non-negotiable design principles and the working conventions (notably: never guess at the wire schema; verify against the real ant CLI) — and docs/ARCHITECTURE.md for how the platform is built.

License

Apache-2.0