This guide owns how to work in the repository: documentation ownership, the repository boundary, workflow and review, required checks and naming. Every other subject has one canonical owner, listed below.
| Subject | Canonical source |
|---|---|
| Design principles, public API fidelity, settings and data ownership, documentation rules | AGENTS.md |
| Protocol code and documents at each component boundary | Protocol map |
| Projects, keys, resource isolation, administrator authority, secrets and audit concepts | Concepts and ownership |
| Component responsibilities and Session flow | Architecture |
| Developer setup, repository map and focused checks | Develop OpenAgentCore |
| API callers, credentials and route inventory | API index |
| Public wire semantics and protocol coverage | Agents API contracts |
| Machine connection routes | Machine connection API |
| Core service setup, tests and generation | Core service guide |
| Core implementation constraints beyond the public contracts | Implementation constraints |
| Environment ownership, preparation, Skills, Plugins, packages and MCP bindings | Environments |
| Built-in Harness identifiers and display names | internal/harnessconfig/builtin/catalog.json and its generated reference |
| Harness registration, service qualification and acceptance | Harness onboarding |
| Harness capabilities by placement | Harness capabilities |
| Harness selection, model providers and native parameters | Model execution |
| Provider registration and lifecycle | Sandbox Provider guide |
| Sandbox deployment, selection and administrative transitions | Sandbox deployment |
| Operator node tasks | Nodes guide |
| Codex, Claude and MiniMax Runtime adapters and images | Codex, Claude, MiniMax |
| Claude private SDK bridge | Claude SDK adapter |
| E2B template construction | E2B template builder |
| E2B and microsandbox Provider helper implementation | E2B helper, microsandbox helper |
| Runtime telemetry responses | Runtime telemetry API |
| Runtime observation, sampling, retention and export | Runtime observability |
| Distribution builds, Runtime image builds, CI and publication | Maintainer guide |
| Website: landing page, documentation site build and GitHub Pages publication | Website guide |
| Self-hosted Runtime installation, recovery and local operation | Self-hosted execution |
| Installer lifecycle, locking, generated state, managed HTTPS and downloads | Installer design rules |
| Operator installation and alternatives | Installation, installation options |
| Settings, defaults, files and installation layout | Configuration |
| Operator commands, keys, backup and version policy | Operations |
| Web console request boundary and sign-in | Console server |
| Web page behavior and visual rules | Web product, Web design |
| Application example behavior and local operation | Application example |
This repository contains the Core API and database, Runtime daemon, Harness and Sandbox Provider adapters, shared protocol packages, Web administrator console and their build and test tools. Product applications stay outside that service boundary. Keep the external Parsar product's server/, apps/parsar/, CLI, plugins and deployment stack in its own repository; do not automatically sync or delete its Core copy. Go imports resolve through this repository's module.
Core must build, deploy and run independently of product services, frontends and databases. Applications follow the public API boundary; their feature backlogs do not define Core's public protocol or storage model. Applications that share a PostgreSQL server with Core must use separate databases, credentials and migrations.
- Parsar owns users, workspaces, business authorization, Agent/Team definitions, capabilities, product conversations, IM/sharing, approval decisions and billing. It uses Core for execution.
- A product conversation may reference several execution Sessions. Core owns native engine session identities; an execution Session has its own lifetime, separate from a daemon connection, process or sandbox.
- Build application orchestration on the public Session and event contract. Product cursor replay must be an explicit product extension. Business Team orchestration belongs to the application; Core's pinned
multi_agentand Subagent resources remain part of the public contract. - Daemon Skill/SP authoring is a product operation: forward it through a scoped product callback that checks the original requester and workspace. A Runtime credential alone must not authorize business writes.
example/parsar/ is an optional, independently started Agent workbench maintained in this repository, with no dependency on the external Parsar product repository. Its README owns its product behavior. The boundary rules are:
- It calls only public
/v1APIs. Its Project key stays server-side; it never holds a Core key or issues machine credentials. Self-hosted connection displays the public Session installation command unchanged; Core owns bootstrap authorization and machine credential issuance. - It may keep a small product-owned SQLite database (Node's built-in module, Node 22.13+), outside the checkout and isolated by Core origin and Project key fingerprint. Provider keys never reach the browser.
- Core owns Skills and all execution and history state. The example stores only Session references and pending creation requests with stable idempotency keys.
- Product resources use
/app/and never become Core API or database conventions. - It is excluded from Core distributions and cannot become a service dependency.
- Record the requirements, acceptance criteria and scope.
- Work in an isolated Git worktree on a feature branch and submit a PR. Do not edit or commit implementation directly on
main. - Make only the changes that scope needs; keep unrelated refactors separate.
When documents conflict, apply the latest explicit user decision and update the affected current guidance. Recorded evidence does not override it.
If requirements are unresolved, object ownership is unclear, or a design would need parallel compatibility paths, raise the issue with a concrete recommendation and tradeoffs before implementing it. Continue independent work meanwhile. Do not silently preserve obsolete private designs.
Record unrelated findings without automatically starting them. Scope compatibility claims to the operations and placements verified.
- Search for existing formatters, parsers, validation and error mappers before adding one. Keep one error mapper per API surface.
- Share frontend formatting and labels in
apps/web/src/lib/; reuse components and tokens. - Split growing files at an existing ownership boundary instead of adding unrelated responsibilities.
- Use
internal/obs/logfor logs. Keep credentials out of source and logs. Harness profiles must not copy Runtime tool environment values; see the environment contract. - Require absolute user-supplied working directories.
- Keep test artifacts under
~/.oac/. - New or changed routes identify their caller and credential in the API index and link their detailed contract.
- After implementation and validation, have a fresh independent subagent review the complete diff.
- Give it only the requirements, acceptance criteria, boundaries, repository path and comparison baseline. Do not give an implementation summary, self-assessment or earlier findings. Explain these criteria to the user.
- Fix substantiated in-scope findings, validate, then use another fresh reviewer.
- If the cycle repeats, reassess design and scope before adding changes. Report an unresolved blocker instead of broadening the task.
Do not use codex exec as a substitute reviewer.
Toolchain setup and focused commands are in Develop OpenAgentCore. CI coverage, caches and release publication are owned by the maintainer guide.
Validate only the current diff and the behavior and consumers it directly affects. Choose the smallest focused checks that establish the change is correct; include migration or cross-component tests only when those behaviors are affected. A code review, documentation edit or CI configuration change does not require a full repository test run. After a follow-up edit, rerun only checks affected by that edit. Record what passed and any validation limits.
The CI selection policy identifies affected groups; it does not require running every target in a selected group locally when narrower checks cover the change. The Makefile keeps make check available for an explicitly requested full validation and release qualification. Releases require the full gate. Live acceptance applies when native execution behavior is affected.
| Variable | Value |
|---|---|
OAC_TEST_DATABASE_URL |
A dedicated test database. The full gate fails when it is missing. |
OAC_TEST_OFFICIAL_SDK_PYTHON |
The pinned official SDK interpreter |
The role needs CREATE DATABASE: tests of database-wide state, such as the execution lease and the provider identity, create and drop isolated oac_*_tests databases. Tests must not bypass the production provider-switch guard.
-
internal/harnessconfig/builtin/catalog.jsonis the single authored public Harness registration list.make generate-harness-cataloggenerates Go configuration/profile registration, client identifiers/names and the reference;make openapiderives the matching enums.make check-harness-catalogverifies freshness in the full gate. Native configuration rules stay in their adapter declarations; Core qualification and Runtime availability stay separate. -
make sqlc-generateowns onlyservices/core/internal/db/sqlc(sqlc v1.29.0). Do not rewrite landed migrations. -
make check-runtime-contractis the focused Core–Runtime contract entry point; see Contract verification. It also runs throughcheck-goandcheck-core.
Use official SDKs and upstream types or schemas where suitable. Validate raw HTTP payloads and observable workflows alongside SDK behavior. API changes preserve the pinned contracts, coverage ledger, official-client tests and Core's independent build. Verify the official-client workflow before application integration; an OpenAI endpoint is a test target only when the required capabilities and credentials are available.
Controlled fixtures and synthetic model responses qualify deterministic behavior. Live execution acceptance calls a real model API through Core, the daemon and the Harness adapter. Direct native probes establish feasibility. Keep provider credentials in private test configuration, outside source, logs and task records.
For wire details unspecified by the pinned SDK, probe resources you own and retain request evidence. Distinguish observed behavior from guarantees, accepted profiles from complete coverage, and provider connectivity from deployment qualification. Maintain those distinctions in the coverage ledger.
Native adapter changes require their build/check targets and live provider acceptance. Follow Harness qualification for native model execution. State which checks ran, which used fixtures and which lacked prerequisites. Changes to native package pins require the same qualification; build the MiniMax companion from this revision's pinned patched sources.
| Surface | Current name |
|---|---|
| Runtime binary | oac-daemon |
| Filesystem and initialization helpers | oac-* |
| Runtime settings | OAC_RUNTIME_* |
Reserved Environment env prefix |
OAC_ |
| Provider ownership labels | io.oac.* |
| E2B metadata | oac_* |
Provider bootstrap, Runtime images and Harness adapters must agree on these names. The separate Parsar product integration settings keep their own names.
The installation version policy owns release changes and preservation of installed data and resources.
Use OpenAgentCore for public project branding. The canonical mark is docs/assets/openagentcore-logo.svg; Web uses its outline with cropped transparent margins, theme-aware favicon colors and dark-surface inversion. The README banner is docs/assets/openagentcore-banner.jpeg. The example/parsar/ workbench keeps its own name, logo and favicon. Preserve external repository URLs and data identifiers when changing display copy.
make check-names scans tracked text for retired branding, GitHub organization, settings and installed command names. Each exception in scripts/name-allowlist.json names a path glob, a regular expression and a reason.
- An exception covers only its matched text: an allowed repository import cannot hide a retired setting elsewhere on the line.
- Keep exceptions narrow and explain the preserved contract or detection input.
- The guard fails on an exception that excuses no retired identifier. Remove an exception together with the last text it covers.
These identities stay unchanged:
- public
AgentCoreError, upstream contract fields and the separate Parsar product; - persisted credential encryption domains and native-session resume keys, so existing data can be decrypted and Sessions can resume.
Detection inputs name the identifiers they reject. Landed migrations keep their original identifiers; application and operator examples use the current names.