open-managed-agents 0.1.0

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,248 @@
+# Open Managed Agents
+
+**Claude Managed Agents, self-hosted.**
+
+Swap the `base_url` in your Anthropic SDK and your agents run here instead:
+same API, same event stream, same sandboxed execution — but the sessions,
+files, and sandboxes live on your machines, under your policies.
+
+> **Where OMA stands today:** wire-compatible on the synchronous single-agent
+> core — agents, sessions, sandboxes, tools, skills, MCP, vaults, SSE — with
+> sandbox security and egress controls that go beyond CMA's documented
+> self-hosted baseline. The orchestration/persistence layer (multi-agent
+> runtime, memory stores,
+> scheduled deployments, webhooks, outcomes) is deliberately deferred. See
+> **[PARITY.md](PARITY.md)** for the full domain-by-domain scorecard and the
+> active parity worklist, and **[ALPHA.md](ALPHA.md)** for the first-user
+> alpha readiness plan.
+
+## Quickstart
+
+Start with the canonical source-checkout guide:
+
+**[Getting Started](docs/getting-started.md)**
+
+The alpha path is:
+
+```bash
+git clone https://github.com/oneryalcin/open-managed-agents.git
+cd open-managed-agents
+npm ci
+npm link
+oma doctor
+oma smoke --local-compatible
+oma smoke --egress
+export ANTHROPIC_API_KEY="..."
+oma up
+```
+
+`oma smoke --local-compatible` is the no-paid-API proof: it starts a temporary
+OMA server, loopback OpenAI-compatible model fixture, and Docker-local sandbox,
+then verifies model discovery, agent/session creation, a real `bash` tool call,
+events, and cleanup.
+
+`oma smoke --egress` extends that deterministic proof through the real
+Docker-local egress boundary: npm, uv/PyPI, and GitHub must work under the
+reviewed preset while an unrelated HTTPS destination remains denied.
+
+`oma up` starts the durable local appliance in the foreground, stores data
+under `~/.oma`, and prints the console URL plus the first workspace API key
+once. Docker deployments have the pinned approved-HTTPS sidecar capability,
+but every environment remains offline unless its immutable allowlist selects a
+reviewed preset or custom hosts. Use that workspace key in the bundled console
+to create an agent, environment, session, and prompt. If the key was not saved,
+mint another while the server is running:
+
+```bash
+oma keys mint
+```
+
+Interactive, air-gap-safe OpenAPI documentation is served at `/docs/`, with
+the same schema available to tools at `/openapi.json`. The documentation lists
+only routes OMA currently ships; workspace and admin credentials entered in the
+UI stay in page memory and are not persisted.
+
+Then point the ordinary Anthropic SDK at it — no OMA-specific client:
+
+```python
+import anthropic
+
+client = anthropic.Anthropic(
+    base_url="http://127.0.0.1:4180",
+    api_key="oma_...",  # printed on first boot
+    default_headers={"anthropic-beta": "managed-agents-2026-04-01"},
+)
+
+agent = client.beta.agents.create(name="helper", model="claude-sonnet-5")
+env = client.beta.environments.create(
+    name="dev",
+    config={"networking": {"type": "limited", "allowed_hosts": []}},  # default-deny
+)
+session = client.beta.sessions.create(agent=agent.id, environment_id=env.id)
+
+with client.beta.sessions.events.stream(session.id) as stream:
+    client.beta.sessions.events.send(session.id, events=[
+        {"type": "user.message", "content": [{"type": "text", "text": "hello"}]},
+    ])
+    for event in stream:
+        print(event.type)
+```
+
+A complete working example (file mounts, custom tools, tool confirmations,
+Streamlit UI) lives in
+[examples/ship-your-first-managed-agent](examples/ship-your-first-managed-agent/README.md).
+Config overrides, model providers, and key provisioning:
+[Development and deployment setup](docs/dev-deployment.md).
+
+## Why This Exists
+
+Managed Agents give agents a durable place to work: sessions, event history,
+streaming updates, custom tools, and sandboxed filesystem/shell execution. The
+hosted version is convenient, but some teams need the same API shape with
+their own runtime, data boundary, sandbox policy, or deployment environment.
+OMA is that control plane.
+
+## How It Is Built
+
+Three habits shape every slice of this codebase, and they are the reason to
+trust it over a feature checklist:
+
+- **Wire parity is measured, not assumed.** Behavior is cloned by probing the
+  hosted API and recording the evidence — error envelopes, middleware
+  ordering, event sequences — before implementation
+  (`scratch/`, [docs/references/](docs/references.md)). When hosted says 405
+  before auth, so do we.
+- **Everything fails closed.** Unknown config values refuse to start; auth
+  without durable storage refuses to start; sandbox providers must be
+  explicitly enabled; builtin tools without a provider refuse to run. The
+  default is always the safe posture, never the convenient one.
+- **Narrow surface, high rigor.** Every slice ships with adversarial review,
+  mutation-checked tests, and a plan document recording what was decided and
+  why ([docs/plans/](docs/index.md)). We would rather do fewer things whose
+  failure modes are known than more things whose failure modes are a surprise.
+
+## Current Status
+
+A working single-node appliance: durable, authenticated, multi-tenant on one
+node, with real sandboxed execution. Not yet full parity with the hosted
+Managed Agents beta surface.
+
+What works today, at outcome level:
+
+- **One command boots it** — durable SQLite storage, fail-closed auth, and a
+  first-boot API key ([plan 0115](docs/plans/0115-appliance-entrypoint.md)).
+- **The full agent loop runs**: agents, environments, sessions, file mounts,
+  streaming events with reconnect/replay, custom-tool round trips, permission
+  gating, interrupts — on the Pi runtime with crash-safe recovery of pending
+  work.
+- **Multi-tenant on one node**: hashed `x-api-key` workspaces, per-workspace
+  admission limits, request idempotency on the retry-sensitive endpoints
+  ([plan 0113](docs/plans/0113-workspace-authentication-admission.md)).
+- **Real isolation for builtin tools**: Docker-local and microsandbox-local
+  providers behind a fail-closed selection boundary.
+- **Credentialed sandbox egress + secrets at rest**: default-deny network
+  policy per environment, an envelope-encrypted secrets store, and boundary
+  credential injection — sandboxed agents reach allowlisted hosts with
+  secrets they can never read
+  ([ADR 0016](docs/adrs/0016-egress-proxy-and-secret-injection.md)).
+- **MCP servers with vault-backed auth**: sessions connect to MCP servers
+  behind `OMA_ENABLE_MCP` — SSRF-guarded, `always_ask` by default. Credentials
+  live in `/v1/vaults` (`static_bearer` and `mcp_oauth`); OAuth tokens refresh
+  themselves (lazy on use, a proactive in-process ticker, and a 401-driven
+  retry) and rotate warm connections without reconnecting. Access tokens,
+  refresh tokens, and client secrets are injected control-plane-side and
+  leak-swept out of tool results and events — the same "usable but never
+  readable" boundary the sandbox egress applies, now on the auth leg
+  ([plan 0122](docs/plans/0122-mcp-connector.md)).
+- **An admin API and a bundled operator console**, served by the appliance at
+  `/console`: browse agents, sessions, events, spans, files, and vaults with a
+  workspace key, and validate an `mcp_oauth` credential in place; create
+  workspaces, mint/revoke API keys, and inspect per-credential refresh health
+  with the admin key ([plan 0119](docs/plans/0119-admin-api.md),
+  [plan 0120](docs/plans/0120-dashboard.md),
+  [plan 0125](docs/plans/0125-console-vaults-mcp.md)). Fully self-contained —
+  no CDN at first paint; browser keys live in page memory only.
+- **Custom skills execution**: upload/version private skill bundles, attach
+  them to agents, snapshot concrete content at session creation, advertise the
+  skill through Pi, and read or execute its root-owned files inside the Docker
+  sandbox under `/workspace/skills`. Session snapshots remain reproducible
+  after source deletion; the live exit smoke covers model discovery, `read`,
+  `bash`, leak checks, tamper resistance, and cleanup
+  ([plan 0126](docs/plans/0126-skills-execution.md)).
+
+- **Observability.** `GET /health` (liveness + readiness, compose
+  healthcheck), fail-closed Prometheus `/metrics`, and structured JSON logs
+  with programmatically enforced secret redaction
+  ([plan 0121](docs/plans/0121-observability.md)).
+
+What's still missing — the
+[appliance product roadmap](docs/plans/0114-appliance-product-roadmap.md) is
+the authoritative sequencing:
+
+- session usage metering (`usage` is `null`);
+- broader event-topology parity, file-upload idempotency, remote sandbox
+  providers, and RBAC within a workspace.
+
+## Architecture
+
+OMA keeps the **harness** separate from **compute**.
+
+The harness is the trusted control plane: API requests, session state, event
+history, model/runtime orchestration, custom-tool correlation, approvals, and
+recovery state.
+
+Compute is the sandbox execution plane: shell commands, filesystem changes,
+packages, and generated artifacts.
+
+That split lets applications keep secrets, auth, billing, audit logs, and
+human review outside the untrusted coding sandbox.
+
+## Compatibility
+
+The north star is Claude Managed Agents wire compatibility: same endpoint
+family, Anthropic-shaped error envelopes, persisted session event stream, SSE
+replay and reconnect behavior, public custom-tool use/result events. Details
+and intentional deviations:
+[ADR 0004](docs/adrs/0004-managed-agents-rest-sse-surface-as-north-star.md).
+
+## Stack
+
+| Layer | Current choice |
+| --- | --- |
+| Control plane | TypeScript + Hono |
+| Runtime engine | Pi Agent SDK |
+| Persistence | SQLite (single-node appliance); Postgres is the scale-out target behind existing store interfaces |
+| Sandbox providers | Docker-local and microsandbox-local, fail-closed selection |
+
+The default sandbox guest is an OMA-owned, multi-architecture image pinned by
+immutable digest. The alpha coding image includes Node/npm, Python/uv, Git,
+curl, jq, Bash, ripgrep, archive tools, and a basic native-build toolchain. It
+is about 256 MiB compressed per platform and remains non-root with a read-only
+root filesystem. Installed tools do not imply network access: environments are
+still default-deny and package-registry access must be explicitly allowlisted.
+
+## Development
+
+```bash
+npm ci
+npm run typecheck
+npm test
+```
+
+Common tasks are also available through thin Make targets (`make check`,
+`make ui`, `make server`, `make parallel-docker-smoke`); see
+[Development and deployment setup](docs/dev-deployment.md).
+
+Deeper docs:
+
+- [Docs index](docs/index.md) — every plan, ADR, and reference note
+- [Appliance product roadmap](docs/plans/0114-appliance-product-roadmap.md)
+- [First Docker-local run](docs/tutorials/docker-local-first-run.md)
+- [Examples](docs/examples.md)
+- [Architecture](docs/architecture.md) · [Scope](docs/scope.md) · [ADRs](docs/adrs/)
+
+## License
+
+[Elastic License 2.0](LICENSE): free to use, copy, modify, and distribute —
+personally or inside your company — with one main limitation: you may not
+offer OMA itself to third parties as a hosted or managed service.