open-managed-agentsDeepSeek Harness plugin

Open Managed Agents

Open-source alternative to Claude Managed Agents — and a foundation for open-source, self-hosted Claude Tag-style agents.

🌐 openma.dev · 📖 docs.openma.dev · 💬 github.com/openma-ai/open-managed-agents

Write a harness. Deploy. The platform runs it — with sessions, sandboxes, tools, memory, vaults, Slack/GitHub/Linear integrations, and crash recovery out of the box. Drop-in compatible with the Claude Managed Agents API; runs on Cloudflare Workers + Durable Objects, or docker compose up on your own box.

Use Open Managed Agents when you want:

• A self-hosted Claude Managed Agents API implementation.
• An open-source, self-hosted Claude Tag-style workflow with BYOK model credentials.
• MCP, private tools, encrypted vaults, and durable sessions under your own deployment boundary.

Compare: Claude Tag alternative · Open-source Claude Tag · Self-hosted Claude Tag

Two ways to run OMA

The same harness, business logic, and event-log model run on both. Pick the one that matches your hosting story:

Same SDK. Same /v1/agents / /v1/sessions API. Same Console UI. Same crash-recovery semantics. Switch between them by changing env vars, not code.

Quick start: self-host (Docker)

bash
1git clone https://github.com/openma-ai/open-managed-agents.git
2cd open-managed-agents
3cp .env.example .env
4
5# Two secrets are required before first boot — both generated locally:
6#   BETTER_AUTH_SECRET   — signs Console sessions
7#   PLATFORM_ROOT_SECRET — encrypts credentials, model-card API keys, integration tokens at rest
8#                          (lose it and every encrypted row is unreadable — back it up)
9$EDITOR .env
10# BETTER_AUTH_SECRET=$(openssl rand -hex 32)
11# PLATFORM_ROOT_SECRET=$(openssl rand -base64 32)
12#
13# Optional: ANTHROPIC_API_KEY lets the first agent run without a Model Card.
14# In production, add a Model Card per tenant from the Console instead.
15
16# SQLite + LocalSubprocess sandbox (default — fastest path)
17docker compose up -d
18
19# Or Postgres backend
20# docker compose -f docker-compose.postgres.yml up -d
21
22curl localhost:8787/health
23# → {"status":"ok","backends":{"db":"sqlite ..."}, ...}
24
25open http://localhost:8787   # Console UI on the same port

Smoke test the harness end-to-end:

bash
AID=$(curl -s -X POST localhost:8787/v1/agents -H 'content-type: application/json' \
  -d '{"name":"hello","model":"claude-sonnet-4-6","tools":[{"type":"agent_toolset_20260401"}]}' | jq -r .id)

SID=$(curl -s -X POST localhost:8787/v1/sessions -H 'content-type: application/json' \
  -d "{\"agent\":\"$AID\"}" | jq -r .id)

curl -s -X POST localhost:8787/v1/sessions/$SID/events -H 'content-type: application/json' \
  -d '{"events":[{"type":"user.message","content":[{"type":"text","text":"Run: uname -a"}]}]}'

Full self-host guide (sandbox modes, Postgres, BoxRun, vault sidecar, Console UI, operator gotchas): docs.openma.dev/self-host/overview

Quick start: Cloudflare deploy

Requires Workers Paid plan (for Durable Objects + Containers).

bash
1git clone https://github.com/openma-ai/open-managed-agents.git
2cd open-managed-agents
3pnpm install
4
5# Local dev (no CF account needed) — wrangler dev with simulators
6cp .dev.vars.example .dev.vars && $EDITOR .dev.vars
7# Same two-secret setup as Docker — PLATFORM_ROOT_SECRET is required to start
8pnpm dev
9# API   → http://localhost:8787
10# Console → http://localhost:5173
11
12# Deploy
13npx wrangler login
14npx wrangler kv namespace create CONFIG_KV   # paste id into wrangler.jsonc
15
16# Required secrets (paste each when prompted)
17npx wrangler secret put BETTER_AUTH_SECRET    # openssl rand -hex 32
18npx wrangler secret put PLATFORM_ROOT_SECRET  # openssl rand -base64 32 — back this up
19npx wrangler secret put API_KEY               # initial bootstrap key for the REST API
20
21# Optional — only if you want a tenant-less default LLM (otherwise add a Model Card in the Console)
22# npx wrangler secret put ANTHROPIC_API_KEY
23
24npm run deploy
25# → https://openma.dev (or https://managed-agents.<your-subdomain>.workers.dev for a personal deploy)

What gets deployed:

Create your first agent

The smoke test above works against any deployment. For the Console-driven flow (Model Cards, vaults, integrations) see docs.openma.dev/quickstart. The minimal API equivalent:

bash
1BASE=http://localhost:8787   # or your deployed URL
2KEY=dev-test-key             # whatever you set as API_KEY
3
4AGENT=$(curl -s $BASE/v1/agents \
5  -H "x-api-key: $KEY" -H "content-type: application/json" \
6  -d '{
7    "name": "Coder",
8    "model": "claude-sonnet-4-6",
9    "system": "You are a helpful coding assistant.",
10    "tools": [{ "type": "agent_toolset_20260401" }]
11  }' | jq -r .id)
12
13SESSION=$(curl -s $BASE/v1/sessions \
14  -H "x-api-key: $KEY" -H "content-type: application/json" \
15  -d "{\"agent\":\"$AGENT\"}" | jq -r .id)
16
17# Send a turn AND stream the reply token-by-token in one shot
18curl -N -X POST $BASE/v1/sessions/$SESSION/messages \
19  -H "x-api-key: $KEY" -H "content-type: application/json" \
20  -d '{"content":"Write a Python script that fetches HN top stories"}'

For long-lived sessions use GET /v1/sessions/$SESSION/events/stream — replays history on connect, never closes.

Architecture

A meta-harness is not an agent — it's the platform that runs agents. It defines stable interfaces for everything an agent needs, and stays out of the way of the agent loop:

┌─────────────────────────────────────────────────────────┐
│  Harness (the brain — your code)                        │
│  - Reads events, builds context, calls the model        │
│  - Decides HOW: caching, compaction, tool delivery      │
│  - Stateless: crash → rebuild from event log → resume   │
├─────────────────────────────────────────────────────────┤
│  Meta-Harness (the platform — SessionDO)                │
│  - Prepares WHAT is available: tools, skills, history   │
│  - Manages lifecycle: sandbox, events, WebSocket        │
│  - Crash recovery, credential isolation, usage tracking │
├─────────────────────────────────────────────────────────┤
│  Infrastructure (Cloudflare or Node self-host)          │
│  - Event log: Durable-Object SQLite (CF) or SQLite/Pg   │
│  - Sandbox: CF Containers / subprocess / LiteBox / E2B  │
│  - Storage: KV + R2 (CF) or local FS (self-host)        │
└─────────────────────────────────────────────────────────┘

The platform prepares what is available. The harness decides how to deliver it to the model.

Write a Harness

The default harness works out of the box. When you need custom behavior — different caching, compaction, context engineering — write your own:

typescript
1// my-harness.ts
2import { defineHarness, generateText, stepCountIs } from "@open-managed-agents/sdk";
3
4export default defineHarness({
5  name: "research",
6
7  async run(ctx) {
8    let messages = ctx.runtime.history.getMessages();
9
10    // Your context engineering
11    messages = keepOnly(messages, ["web_search", "web_fetch"]);
12
13    // Your caching strategy
14    markLastN(messages, 3, { cacheControl: "ephemeral" });
15
16    // Your loop — tools, sandbox, broadcast are platform-provided
17    const result = await generateText({
18      model: ctx.model,
19      system: ctx.systemPrompt,
20      messages,
21      tools: ctx.tools,
22      stopWhen: stepCountIs(50),
23      onStepFinish: async ({ text }) => {
24        if (text) ctx.runtime.broadcast({
25          type: "agent.message",
26          content: [{ type: "text", text }],
27        });
28      },
29    });
30
31    await ctx.runtime.reportUsage?.(result.usage.inputTokens, result.usage.outputTokens);
32  },
33});

Deploy it:

bash
oma deploy --harness my-harness.ts --agent agent_abc123

The harness is bundled into the agent worker at build time. Your code runs in the same isolate as SessionDO — direct access to the event log, sandbox, and WebSocket broadcast. No RPC, no serialization boundary.

API

Compatible with the Claude Managed Agents API. Same endpoints, same event types, works with existing SDKs.

http
POST   /v1/agents                          # Create agent
GET    /v1/agents                          # List agents
GET    /v1/agents/:id                      # Get agent
PUT    /v1/agents/:id                      # Update agent
DELETE /v1/agents/:id                      # Delete agent
POST   /v1/agents/:id/archive             # Archive agent
GET    /v1/agents/:id/versions            # Version history
GET    /v1/agents/:id/versions/:version   # Get specific version

http
POST   /v1/environments                   # Create environment
GET    /v1/environments                   # List environments
GET    /v1/environments/:id               # Get environment
PUT    /v1/environments/:id               # Update environment
DELETE /v1/environments/:id               # Delete environment

http
1POST   /v1/sessions                        # Create session
2GET    /v1/sessions                        # List sessions
3GET    /v1/sessions/:id                    # Get session
4POST   /v1/sessions/:id                    # Update session
5DELETE /v1/sessions/:id                    # Delete session
6POST   /v1/sessions/:id/archive           # Archive session
7
8POST   /v1/sessions/:id/events            # Send events (user messages)
9GET    /v1/sessions/:id/events             # Get events (JSON or SSE)
10GET    /v1/sessions/:id/events/stream      # SSE stream
11
12POST   /v1/sessions/:id/resources          # Attach resource
13GET    /v1/sessions/:id/resources          # List resources
14DELETE /v1/sessions/:id/resources/:resId   # Remove resource

http
POST   /v1/vaults                          # Create vault
POST   /v1/vaults/:id/credentials          # Add credential
GET    /v1/vaults/:id/credentials          # List (secrets stripped)

http
1POST   /v1/memory_stores                                        # Create store
2GET    /v1/memory_stores                                        # List stores
3GET    /v1/memory_stores/:id                                    # Retrieve store
4POST   /v1/memory_stores/:id/archive                            # Archive (one-way)
5DELETE /v1/memory_stores/:id                                    # Delete store + memories + versions
6
7POST   /v1/memory_stores/:id/memories                           # Create/upsert memory {path, content, precondition?}
8GET    /v1/memory_stores/:id/memories?path_prefix=&depth=N      # List memories (metadata)
9GET    /v1/memory_stores/:id/memories/:mid                      # Retrieve memory (with content)
10POST   /v1/memory_stores/:id/memories/:mid                      # Update memory {path?, content?, precondition?}
11DELETE /v1/memory_stores/:id/memories/:mid                      # Delete memory
12
13GET    /v1/memory_stores/:id/memory_versions?memory_id=         # Audit history (newest first)
14GET    /v1/memory_stores/:id/memory_versions/:ver_id            # Single version (with snapshot content)
15POST   /v1/memory_stores/:id/memory_versions/:ver_id/redact     # Redact prior version (refuses live head)

bash
oma memory stores create "User Preferences"
oma memory write <store-id> /preferences/formatting.md --content "Always use tabs."
oma memory ls <store-id> --prefix /preferences/
oma memory versions <store-id> --memory-id <mem-id>

http
POST   /v1/files                           # Upload file
GET    /v1/files/:id/content               # Download file
POST   /v1/skills                          # Create skill
GET    /v1/skills                          # List skills

Built-in Tools

The agent_toolset_20260401 provides:

Derived tools are auto-generated based on session config:

(Memory Stores do not add bespoke tools — agents access them as filesystem mounts at /mnt/memory/<store_name>/ via the standard file tools above.)

MCP servers

OMA registers any Model Context Protocol server attached to an agent. Each upstream tool surfaces to the model as mcp__<server>__<tool> (double underscore — copy the name exactly). Up to 20 servers per agent.

Credentials never enter the sandbox; the outbound resolver matches by host and injects at forward time.

bash
# Servers attach to the agent (not the session)
curl -X PUT $BASE/v1/agents/$AGENT -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{"mcp_servers":[{"name":"linear","type":"url","url":"https://mcp.linear.app/mcp"}]}'

# Bind an OAuth credential via Vault
oma connect linear --vault $VAULT_ID

Tool discovery is bounded at 15 s per server; one bad server logs and skips, the rest stay live. Full design: docs.openma.dev/build/vault-and-mcp.

Skills

A skill is a SKILL.md plus reference files (templates, schemas, examples). At session start the platform mounts everything under /home/user/.skills/{name}/ in the sandbox and inlines the SKILL.md body directly into the system prompt — no lazy read, no follow-up read tool call. Format is compatible with Anthropic's Claude Code skills.

Create a skill (JSON; files inlined):

http
POST /v1/skills
{
  "files": [
    { "filename": "SKILL.md", "content": "---\nname: invoice-parser\ndescription: Parse supplier invoices.\n---\n\n# Steps\n1. ..." },
    { "filename": "schema.json", "content": "{...}" }
  ]
}

For large skills with binaries: POST /v1/skills/upload multipart with file=<my-skill.zip>.

Attach to an agent with the object form — a bare string array silently does not bind:

json
{ "skills": [{ "skill_id": "skill_abc123", "type": "custom" }] }

The agent's system prompt then receives, at session start:

<source name="skill:skill_abc123">
<skill name="invoice-parser">
{full SKILL.md body}
</skill>
</source>

and the files appear at /home/user/.skills/invoice-parser/SKILL.md etc.

Four built-in skills ship ready to attach (no upload): xlsx, pdf, docx, pptx. Reference them with {"skill_id":"builtin_pdf","type":"anthropic"}.

Vaults & outbound credentials

Tools never see your tokens. When a sandbox makes an HTTP request, an outbound resolver — oma-vault sidecar on self-host (mockttp HTTPS proxy with a trusted self-signed CA), the agent worker's outboundByHost interceptor on Cloudflare — matches the request hostname against the session's vaults, strips any inbound Authorization/x-api-key/x-goog-api-key, injects the real credential, and forwards. A prompt-injected agent has nothing to leak; env | grep TOKEN returns nothing inside the sandbox.

bash
1# Create a vault and add a static bearer bound to api.github.com
2VID=$(curl -sX POST $BASE/v1/vaults -H "x-api-key: $KEY" \
3  -d '{"name":"github-prod"}' | jq -r .id)
4
5curl -sX POST $BASE/v1/vaults/$VID/credentials -H "x-api-key: $KEY" -d '{
6  "display_name": "gh-pat",
7  "auth": {
8    "type": "static_bearer",
9    "token": "ghp_xxx",
10    "mcp_server_url": "https://api.github.com"
11  }
12}'
13
14# Bind on session create
15curl -sX POST $BASE/v1/sessions -H "x-api-key: $KEY" \
16  -d "{\"agent\":\"$AGENT\",\"vault_ids\":[\"$VID\"]}"
17
18# Inside the sandbox: curl https://api.github.com/user → 200, Authorization injected at the network layer

Three credential types share one resolver:

Max 20 credentials per vault. Each forward emits a structured op:"mcp_proxy.forward" log. Full design: docs/mcp-credential-architecture.md, docs.openma.dev/build/vault-and-mcp.

Integrations

Publish an agent into a third-party tool and have it act as a real teammate there — assigned, mentioned, replied to like any other user.

Linear

Make an agent a member of your Linear workspace with its own identity, avatar, and @autocomplete slot. The agent appears in the assignee dropdown, gets pinged on @mentions, replies in the Agent panel, and pushes status back to issues it's working on.

Two install kinds:

The full agent-side playbook (when to ask the human, how to offer browser automation, exactly what to paste into Linear's form) lives at skills/openma/integrations-linear.md.

PAT-mode autopilot — let the bot pick up unassigned issues by label/state/project:

bash
oma linear rules create <pub-id> --label triage --state Backlog --project "Inbox"
oma linear rules list <pub-id>
oma linear rules delete <rule-id>

Inspect / manage:

bash
oma linear list                                       # workspaces
oma linear pubs <installation-id>                     # publications (status=live, persona, caps)
oma linear get <pub-id>                               # single publication
oma linear update <pub-id> --caps issue.read,comment.write,issue.update,…
oma linear unpublish <pub-id>

How it works:

The Linear integration ships in packages/linear/ (provider logic, webhook signing, MCP wiring) with thin CF wrappers in apps/integrations/src/routes/linear/publications.ts.

GitHub

Give an agent its own GitHub App with a real bot identity — assignable on issues, requestable as a reviewer on PRs, posts comments under its own @<slug>[bot] handle. Each agent is a separate App on github.com (per-publication, not a shared marketplace bot), so credentials and audit trails stay isolated.

bash
# (1) Console — humans clicking through a wizard
Integrations → GitHub → Publish agent

# (2) CLI — agents driving openma on a user's behalf
oma github bind <agent-id> --env <env-id>       # → opens one-click GitHub App Manifest flow
oma github handoff <form-token>                 # alt: 7-day URL for an org admin to complete
oma github list
oma github pubs <installation-id>
oma github update <pub-id> --caps pr.read,pr.review.write,issue.comment.write,…
oma github unpublish <pub-id>

bind returns a manifestStartUrl; opening it auto-POSTs an App manifest to github.com/settings/apps/new with redirect URL + webhook URL + recommended permissions baked in. After confirming, GitHub redirects through to "Install on org" and the publication flips to live. Manual fallback: oma github submit <form-token> --app-id … --private-key-file … --webhook-secret … if you registered the App by hand.

Engagement is label-based. On install OMA auto-creates a label (default: lowercased persona name) in every selected repo. Add the label to any issue/PR to engage the bot for every subsequent activity on that thread; remove the label to mute. @<slug>[bot] mention in body or comment is the fallback path (GitHub's @ autocomplete excludes Bot accounts, so it's plain-text).

How it works:

The GitHub integration ships in packages/github/ with thin CF wrappers in apps/integrations/src/routes/github/.

Slack

Publish an agent into a Slack workspace as a dedicated bot — @mentionable in channels, replies in threads, joins DMs, hosts the AI assistant pane. Per-channel sessions: one running session per (publication, channel), with all events in that channel converging on the same session id.

bash
1# (1) Console — humans clicking through a wizard
2Integrations → Slack → Publish agent   # ↑ opens api.slack.com with a pre-filled manifest
3
4# (2) CLI — agents driving openma on a user's behalf
5oma slack publish <agent-id> --env <env-id>    # → returns manifestLaunchUrl + formToken (60 min TTL)
6oma slack submit <form-token> --client-id … --client-secret … --signing-secret …
7oma slack handoff <form-token>                 # alt: 7-day shareable URL for a workspace admin
8oma slack list
9oma slack pubs <installation-id>
10oma slack update <pub-id> --caps message.write,thread.reply,reaction.add,…
11oma slack unpublish <pub-id>

The full agent-side playbook (manifest-flow caveats, GATEWAY_ORIGIN HTTPS requirement, what to paste where, MCP toggle probe) lives at skills/openma/integrations-slack.md.

How it works:

The Slack integration ships in packages/slack/ with thin CF wrappers in apps/integrations/src/routes/slack/.

Operator setup: the integrations gateway needs GATEWAY_ORIGIN pointing at a publicly-reachable HTTPS host — Slack verifies both the OAuth redirect URL and the Events Request URL before letting an install complete.

Project Structure

open-managed-agents/
├── apps/
│   ├── main/              # API worker (Cloudflare) — Hono routes, auth, rate limiting
│   ├── main-node/         # API worker (Node self-host) — same routes on Hono/Node
│   ├── agent/             # Agent worker — SessionDO + harness + sandbox
│   ├── integrations/      # Integrations gateway — Linear / GitHub / Slack OAuth + webhooks
│   ├── oma-vault/         # Vault sidecar — outbound auth-header injection (per-host secrets)
│   ├── console/           # Web dashboard — React + Vite + Tailwind v4
│   ├── docs/              # Docs site (Astro Starlight) — published to docs.openma.dev
│   └── web/               # Marketing site (Astro) — published to openma.dev
├── packages/
│   ├── cli/                       # `oma` CLI — agent / session / integration commands
│   ├── sdk/                       # Harness SDK — defineHarness, generateText helpers
│   ├── api-types/                 # Shared TypeScript types (config schemas, events)
│   ├── http-routes/               # Public REST route definitions (shared by main + main-node)
│   ├── session-runtime/           # Harness runtime — event log, broadcast, recovery
│   ├── sandbox/                   # Sandbox adapters (subprocess / litebox / daytona / e2b / boxrun)
│   ├── credentials-store/         # Encrypted credentials (AES-GCM under PLATFORM_ROOT_SECRET)
│   ├── model-cards-store/         # Encrypted model-card API keys
│   ├── vaults-store/              # Vault definitions + outbound auth wiring
│   ├── linear/  github/  slack/   # Provider logic (OAuth, webhook signing, MCP wiring)
│   ├── integrations-core/         # Provider-neutral persistence interfaces
│   └── integrations-adapters-{cf,node}/  # D1 / KV / Workers + Postgres / FS implementations
├── docs/                  # Internal design RFCs (not the user-facing site)
├── test/                  # Unit + integration tests
└── scripts/               # Deployment + maintenance scripts

Configuration

The variables that gate boot and at-rest safety:

Full list (integrations OAuth credentials, Postgres URL, sandbox tunables, memory-bucket config, Google sign-in, etc.) — see docs.openma.dev/reference/configuration and .env.example / .dev.vars.example.

Model Cards

Per-tenant LLM credentials. An agent references one by setting agent.model = "<model_id>" — the worker looks up the card and signs the outbound request with its api_key, base_url, and headers. This is the canonical replacement for the global ANTHROPIC_API_KEY env var.

Providers are Pi provider ids. The four legacy tags remain migration aliases:

| provider | Pi protocol / use | |---|---|---| | anthropic (ant) | Pi Anthropic Messages; Claude on api.anthropic.com | | openai (oai) | Pi OpenAI Responses/Completions | | Any Pi built-in id | deepseek, openrouter, google, minimax, etc.; Pi owns model metadata and wire behavior | | Custom id | Requires base_url and pi_config.api; compatible aliases still map to Anthropic/OpenAI protocols |

Add one from Console → Model Cards, or via CLI:

bash
oma models create \
  --model-id claude-prod \
  --provider anthropic \
  --model claude-sonnet-4-6 \
  --api-key sk-ant-...
oma models list

REST: POST /v1/oma/model_cards, GET /v1/oma/model_cards, POST /v1/oma/model_cards/:id (rotate), DELETE /v1/oma/model_cards/:id. Create runs a bounded live probe for the legacy Anthropic/OpenAI protocols; other Pi providers return an explicit skipped probe result and are validated when their runtime request is exercised.

There are two model catalogs. Official GET /v1/models lists this tenant's executable Model Cards in the Managed Agents shape, with capabilities and token limits projected from Pi. OMA POST /v1/oma/models/list {provider} lists Pi's built-in catalog while configuring a card and does not require a provider key; the old api_key field remains optional for 0.x Anthropic/OpenAI live discovery.

Agent request controls are versioned with the Agent and inherited by Sessions: model.effort maps to Pi thinking levels (Pi normalizes unsupported levels), model.speed=fast maps to Anthropic fast mode or OpenAI priority tier, and model.inference_geo is preserved in the official API but is not currently a runtime routing input. These controls are not Model Card pi_config fields.

Keys are AES-256-GCM-encrypted at rest under PLATFORM_ROOT_SECRET (label model.cards.keys); list responses surface only the last-4 preview. Rotate by POSTing a new api_key — no redeploy, no key versioning (re-run the backfill script if you rotate PLATFORM_ROOT_SECRET itself).

Testing

bash
npm test          # unit + integration suite
npm run typecheck # zero errors

Documentation

The user-facing docs site lives at apps/docs (Astro Starlight) and is published to docs.openma.dev.

bash
pnpm dev:docs       # local preview at http://localhost:4321
pnpm build:docs     # static build into apps/docs/dist/
pnpm deploy:docs    # build + wrangler deploy (Cloudflare Worker static assets)

The docs/ folder at the repo root contains internal design RFCs — not the user-facing site.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Run tests (npm test && npm run typecheck)
4. Commit your changes
5. Open a Pull Request

License

Apache 2.0