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 |
| 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, bilingual documentation maintenance, 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 | Deployment and Node installer |
| 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.
example/parsar/ is an optional Agent workbench in this repository. Its README owns its product behavior.
- 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.
Follow the worktree rule. Do not edit or commit implementation directly on main.
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 it with a concrete recommendation and tradeoffs before implementing. Continue independent work meanwhile. Do not silently preserve obsolete private designs.
Record unrelated findings without starting them. Scope compatibility claims to the operations and placements verified.
- Apply the simplicity and performance principles when adding structure or optimizing execution.
- Keep one formatter, parser, validator and error mapper per job, and one error mapper per API surface.
- Share frontend formatting and labels in
apps/web/src/lib/. - 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 the current diff and the behavior it directly affects, with the smallest checks that establish correctness. Include migration or cross-component tests only when those behaviors change. A review, documentation edit or CI configuration change does not need a full repository test run. After a follow-up edit, rerun only the checks that edit affects, and record what passed and any limits.
The CI selection policy names affected groups. A narrower check is enough when it covers the change. make check is the full gate for an explicitly requested full validation and for releases. Live acceptance applies when native execution behavior changes.
| 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, and projects the model-provider protocol names ofinternal/modelprovider/config.goto the client;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. 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 acceptance calls a real model API through Core, the daemon and the Harness adapter. Direct native probes establish feasibility only. Keep provider credentials in private test configuration, outside source, logs and task records.
For wire details the pinned SDK does not specify, probe resources you own and retain the request evidence. In the coverage ledger, keep observed behavior distinct from guarantees, accepted profiles distinct from complete coverage, and provider connectivity distinct from deployment qualification.
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 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.