Repository creation, one-time GitHub import, and the terminal client are

documented in the [OpenAgents CLI guide](docs/openagents-cli/index.md).

## Capability status

## Production status

No part of this repository is approved for production deployment yet.

OpenAgents runs at [openagents.com](https://openagents.com) on a three-node

production fleet. The owned Forge is the canonical Git remote for this

repository, and `MirrorWatch` exports accepted `main` commits to GitHub. Every

deployment starts from an exact commit that passed the release gate.

### Implemented and locally gated

### Active capabilities

- GitHub OAuth, encrypted server-side GitHub token storage, sessions, and

  account-scoped data rights.

  interruption recovery, rolling replacement, repository contracts, and a

  disposable packaged-release smoke test.

"Implemented" means the code and local tests exist. It does not mean the

feature has passed staging, security review, failure injection, or a soak.

Availability still depends on repository access, account authority, and the

runtime feature profile. A source module or passing local test does not by

itself establish that a feature is enabled for every production user.

### Disabled by default or staging-only

### Controlled capabilities

- Voice, recording, semantic recall, experimental program paths, and deployment

  workers remain controlled by runtime configuration.

- Direct BEAM loading, relup installation, rolling replacement, and boot

  convergence require isolated three-node staging proof before they can be

  enabled outside a disposable environment.

- The self-hosted forge is being hardened. GitHub remains the canonical remote

  for the OpenAgents platform repository until the proof-gated cutover in ADR

  0007; newly created hosted repositories use OpenAgents as their source of

  truth.

### Planned or blocked on hardening

- Staging qualification and release of repository creation, GitHub import, and

  the OpenAgents CLI.

- Separate web and distributed staging lanes, a full regression matrix,

  failure-injection drills, and a 48-hour soak.

- Any production rollout. Production remains explicitly out of scope until the

  staging plan is complete and separately approved.

- Forge direct loading accepts only verified BEAM changes whose modules match

  the production allowlist. Structural changes use a packaged relup or rolling

  replacement, and boot convergence prevents a restarted node from serving an

  older target.

- Staging remains the qualification environment for changes that require

  browser, distributed-cluster, failure-injection, migration, or configuration

  evidence before production promotion.

Read the [Forge hot loop runbook](docs/operations/forge-hot-loop.md) for the

current deployment contract and production evidence.

## Architecture

## Contributing and source control

Read `AGENTS.md` before changing the application. GitHub is temporarily the

canonical remote during staging hardening. The forge becomes canonical only

after the durability, mirror, restore, and deployment proofs in ADR 0007 pass.

Read `AGENTS.md` before changing the application. Push accepted work to the

owned Forge. `MirrorWatch` maintains GitHub as the public mirror; do not treat

an independently pushed GitHub branch as production authority.

## License

# OpenAgents architecture

Date: 2026-08-20

Date: 2026-08-22

Status: Current product architecture and accepted hardening target

Status: Current production architecture

## Purpose

## Runtime and staging topology

The accepted target has two isolated staging lanes:

Production runs one OpenAgents release on a three-node BEAM fleet. PostgreSQL

holds durable product and deployment authority. The Forge owns Git refs,

promotion targets, build receipts, and deployment receipts. Boot convergence

keeps a restarted node out of service until it matches the live target.

Qualification keeps two isolated staging lanes:

- A web lane proves Phoenix, LiveView, PostgreSQL, authentication, chat, voice,

  data rights, and provider behavior without distributed deployment enabled.

Both lanes use staging-only hosts, credentials, buckets, repositories, service

accounts, and a PostgreSQL instance that does not share a production failure

domain. Production is out of scope until all hardening gates, the complete

staging matrix, failure injection, and the 15-minute pinned-candidate soak pass.

domain. Use staging for browser, migration, configuration, distributed-cluster,

and failure-injection evidence before a production promotion requires it.

`OpenAgents.RuntimeConfig` validates the complete behavior-changing settings

boundary before migrations or traffic. The

feature profile, durable storage requirements, staging-gate admission, and

content-free readiness report.

## Source control transition

## Source control authority

GitHub remains the repository's temporary canonical remote during staging

hardening. The self-hosted forge becomes canonical only through an explicit

cutover after its Git, mirror, artifact, rollback, and recovery gates pass. The

cutover changes contributor instructions and push automation in the same

candidate. After cutover, the forge pushes a read-only GitHub mirror and direct

GitHub pushes become invalid.

The self-hosted Forge is canonical. Contributors and deployment automation push

accepted work to the owned Forge. `MirrorWatch` exports the accepted branch to

GitHub and reports mirror lag separately from deployment state. A GitHub mirror

update cannot promote a deployment, and a direct GitHub push does not become

production authority.

Do not describe the cutover as complete while contributor clones and automated

pushes still target GitHub.

Read [ADR 0007](decisions/0007-cut-over-to-forge-canonical-source-control-after-proof.md)

and the [Forge hot loop runbook](operations/forge-hot-loop.md) for the cutover

decision and current operator procedure.

## Decision records

Date: 2026-08-20

Status: Accepted; cutover pending

Status: Accepted; cutover completed on 2026-08-22

## Context

The product intends to host its canonical Git repositories on the OpenAgents

forge and keep GitHub as a discoverable read-only mirror. This repository still

uses GitHub as its configured canonical remote during staging hardening. A

documentation-only cutover would split contributor and deployment state.

The product hosts its canonical Git repositories on the OpenAgents Forge and

keeps GitHub as a discoverable read-only mirror. Before the cutover, this

repository used GitHub as its configured canonical remote during staging

hardening. A documentation-only cutover would have split contributor and

deployment state.

## Decision

Keep GitHub canonical until the self-hosted Git plane passes authentication,

authorization, durability, mirror, restore, and operational recovery gates.

Perform the cutover as one controlled change that updates contributor

instructions, operator automation, build source, deployment promotion, and

mirror monitoring.

The self-hosted Git plane passed its authentication, authorization, durability,

mirror, restore, and operational recovery gates. The 2026-08-22 cutover updated

contributor instructions, operator automation, build source, deployment

promotion, and mirror monitoring as one controlled change.

After cutover, accept pushes only through the forge for normal operation. Push

a one-way read-only mirror to GitHub, monitor mirror lag, and treat a direct

## Consequences

- Current contributors keep one accurate remote during hardening.

- The future cutover has explicit prerequisites and rollback evidence.

- Contributors use one canonical Forge remote.

- The completed cutover retains explicit prerequisites and rollback evidence.

- GitHub remains available for discovery without becoming a second writable

  authority.

- The application must report canonical-source and mirror state separately.

# Runtime configuration

Date: 2026-08-20

Date: 2026-08-22

Status: Current

configuration raises a diagnostic containing only the setting name and its

requirement; it never echoes a value.

Production releases require `OPENAGENTS_ENVIRONMENT=staging` or `production`.

Production remains locked: `OPENAGENTS_ENVIRONMENT=production` is refused while

`OPENAGENTS_PRODUCTION_DEPLOY_ENABLED=false`. Do not change that setting until

the staging matrix and soak in the hardening plan are complete and an operator

records a separate production decision.

Deployed releases require `OPENAGENTS_ENVIRONMENT=staging` or `production`.

Production startup fails closed unless

`OPENAGENTS_PRODUCTION_DEPLOY_ENABLED=true`. The production cutover recorded

that decision on 2026-08-21; a new environment must still set the value

explicitly and satisfy the rest of this contract.

## Readiness report

at 15 minutes, and captured output at 16 MB. The lane runs read-only against a

disposable clone of a forge repository at an exact revision.

## Required release settings

## Required deployed-release settings

All settings in this section are mandatory in a production release unless

marked conditional. An empty value is accepted only where the table explicitly

says "empty disables." Secrets come from the staging secret manager through

the runtime identity; never put them in images, build arguments, repository

URLs, receipts, or checked-in environment files.

All settings in this section are mandatory in a staging or production release

unless marked conditional. An empty value is accepted only where the table

explicitly says "empty disables." Secrets come from the environment's secret

manager through the runtime identity; never put them in images, build

arguments, repository URLs, receipts, or checked-in environment files.

| Group | Environment setting | Requirement |

| --- | --- | --- |

| Release | `OPENAGENTS_ENVIRONMENT` | `staging`; `production` remains separately locked |

| Release | `OPENAGENTS_ENVIRONMENT` | `staging` or `production` |

| Release | `OPENAGENTS_STAGING_GATE` | Integer `0` through `16`; feature admission is tied to it |

| Release | `OPENAGENTS_STAGING_CLEANUP_ENABLED` | `true` only at staging Gate 12 or later; always `false` elsewhere |

| Release | `OPENAGENTS_PRODUCTION_DEPLOY_ENABLED` | `false` until a later production decision |

| Release | `OPENAGENTS_IMAGE_DIGEST` | Exact `sha256:` image digest at staging Gate 12 and later; empty before that gate |

| Endpoint | `PHX_HOST` | Exactly `staging.openagents.com` in staging |

| Endpoint | `OPENAGENTS_ALLOWED_ORIGINS` | Comma-separated exact HTTPS origins including `https://staging.openagents.com` |

| Release | `OPENAGENTS_PRODUCTION_DEPLOY_ENABLED` | `true` only for an admitted production release; `false` in staging |

| Release | `OPENAGENTS_IMAGE_DIGEST` | Exact `sha256:` image digest in production and at staging Gate 12 or later; empty only before that staging gate |

| Endpoint | `PHX_HOST` | Exactly `staging.openagents.com` in staging; use the admitted public host in production |

| Endpoint | `OPENAGENTS_ALLOWED_ORIGINS` | Comma-separated exact HTTPS origins including the environment's `PHX_HOST` |

| Endpoint | `OPENAGENTS_HTTPS_ALIASES` | Comma-separated hostnames; empty means no aliases |

| Endpoint | `OPENAGENTS_SECURE_COOKIES` | `true` in staging and production |

| Endpoint | `SECRET_KEY_BASE` | Staging-only secret |

| Endpoint | `SECRET_KEY_BASE` | Environment-specific secret |

| Endpoint | `PORT` | Port `1` through `65535` |

| Database | `OPENAGENTS_DATABASE_MODE` | `url` or `socket` |

| Database | `DATABASE_URL` | Required only in `url` mode |

| Database | `OPENAGENTS_DATABASE_IPV6` | Explicit `true` or `false` |

| Database | `POOL_SIZE` | Integer `1` through `200` |

| Database | `OPENAGENTS_MIGRATE_ON_BOOT` | `true` in staging and production |

| GitHub | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | Staging OAuth application credentials |

| GitHub | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | OAuth application credentials for the selected environment |

| GitHub | `GITHUB_REDIRECT_URI` | Exact HTTPS callback on `PHX_HOST` |

| GitHub | `GITHUB_OAUTH_SCOPES` | Exactly `repo,read:org`; repository import needs retained repository access and organization creation needs membership access |

| GitHub | `OPENAGENTS_ADMIN_GITHUB_IDS` | Comma-separated immutable numeric GitHub IDs allowed to use operator surfaces; never use logins |

| GitHub | `GITHUB_TOKEN_ENCRYPTION_KEY` | Base64-encoded 32-byte staging key |

| GitHub | `GITHUB_TOKEN_ENCRYPTION_KEY` | Base64-encoded 32-byte key for the selected environment |

| GitHub | `GITHUB_TOKEN_ENCRYPTION_KEY_ID` | Bounded active-key identifier prefixed with `development-`, `test-`, `staging-`, or `production-` to match the runtime |

| GitHub | `GITHUB_TOKEN_DECRYPTION_KEYS_JSON` | Optional map of at most 16 same-environment prior keys used only during rewrap; omit the active ID |

| Providers | `OPENAI_API_KEY` | Staging-only provider secret; required by the current text provider |

| Providers | `OPENAI_API_KEY` | Environment-specific provider secret; required by the current text provider |

| Providers | `OPENAGENTS_INFERENCE_PROXY_URL` | HTTPS URL without credentials when computers are enabled; empty disables |

| Computers | `OPENAGENTS_MACHINE_TOKEN_TTL_SECONDS` | `300` through `2592000`; Gate 5 uses the 30-day maximum |

| Recording | `VOICE_RECORDING_ENCRYPTION_KEY` | Base64-encoded 32-byte key when recording is enabled; empty disables recording storage |

safe value unless noted. Advancing `OPENAGENTS_STAGING_GATE` admits a feature;

it does not enable it automatically.

The table records compiled defaults and the Gate 5 staging template. It is not

a live production feature inventory. Run `bin/config-readiness` inside the

target release to inspect its redacted feature booleans.

| Feature | Environment setting | Default | Gate 5 staging | Earliest staging gate |

| --- | --- | --- | --- | --- |

| Tool catalog | `OPENAGENTS_FEATURE_TOOLS` | On | On | 5 |

# SCV planning

Date: 2026-08-20

Date: 2026-08-22

Status: OpenCode worker and Codex propose-only driver implemented; Codex runs

now retain durable leases, normalized events, and terminal reports; isolated

staging qualification, durable write effects, and autonomous deployment remain

disabled

Status: OpenCode worker, Codex propose-only driver, and operator-started

read-only deployment lane implemented; durable write effects and autonomous

promotion remain disabled

## Outcome

The intended end state includes automatic deployment. The first implementation

must not bypass the repository's current safety contracts:

- GitHub remains canonical until the proof-gated cutover in

- The Forge is canonical after the proof-gated cutover in

  [ADR 0007](decisions/0007-cut-over-to-forge-canonical-source-control-after-proof.md).

- Forge fleet deployment remains disabled until the isolated staging gates in

  the [integration hardening plan](2026-08-20-integration-hardening-and-staging-readiness-recommendations.md)

  pass.

  SCV candidates must use its authenticated push and promotion boundaries.

- Forge fleet deployment is active. The SCV deployment lane remains a bounded,

  operator-started, read-only work job and does not grant repository writes or

  promotion authority.

- `SELF-EDIT-001` currently requires a human promotion. Enabling an SCV to

  promote a candidate requires an explicit invariant and architecture amendment,

  a typed service principal, and a policy-bound promotion receipt. Do not encode

the WAL remains ref authority. Use compare-and-swap against the recorded base.

Do not update a bare repository ref directly from application code.

Before Forge becomes canonical, keep an SCV in propose-only mode and reconcile

its run refs through the existing GitHub review process. After the ADR 0007

cutover, decide whether `scv/integration` becomes the default branch or merges

into it through another policy-controlled fast-forward. Do not operate two

writable canonical histories.

The Forge is canonical. Keep an SCV in propose-only mode until a separately

admitted write policy exists. Decide whether `scv/integration` becomes the

default branch or merges into it through another policy-controlled

fast-forward. Do not operate a second writable history through the GitHub

mirror.

### Workspace lifecycle

- an executor path under `/tmp` in staging or production;

- an automatic mode before Forge deployment, boot convergence, durable

  artifacts, and isolated staging are enabled;

- `production_auto` while production deployment remains globally disabled;

- `production_auto` without a separate production-autonomy admission and

  policy receipt;

- multiple active runs in the first policy revision;

- multiple repository writers for one integration history;

- a benchmark comparison across incompatible provenance;