BoardAgent

Work through your own agent. Keep the board’s canonical records, permissions and confirmations in one self-hosted service.

BoardAgent is a self-hosted, MCP-native board-governance system of record. Directors, observers, management, and the secretariat work through their own MCP-capable agents. BoardAgent has no governance portal and runs no server-side AI: it stores canonical machine-readable records, enforces procedure and authority, and produces tamper-evident evidence.

Status on 15 September 2026: private hardened beta, deployed for a supervised synthetic trial. Candidate 57f1638 passed the full local regression net (tiers T0 to T9, 3,306 test executions, 100 % mutation score on the deterministic kernel, clean image scan) and the native Linux qualification including the frozen performance targets, and was installed on a synthetic VPS by the preserving-upgrade procedure with a rehearsed backup and public HTTPS/OAuth verification. Four real people then enrolled with passkeys and completed onboarding through their own agents, a charter was activated as a governance profile with clause citations, and a written resolution was circulated and put to a vote. That is the state of the evidence; it is not a public production release and no security certification is claimed. Use synthetic information only.

What that trial also showed, honestly: binding acts (votes, invitations, governance changes) are confirmed through an MCP elicitation form that today only Claude Code renders, so other clients can read the board but cannot act on it; the administrator step-up needs a real passkey within ten minutes and a browser that keeps its session can defeat it silently; and the pre-upgrade recovery rehearsal decrypts the whole WAL archive. These are the first items of the roadmap. The verification register identifies implementation and test pointers; known limitations and the readiness plan distinguish historical proof, pending work and actual human acceptance. The execution record retains an earlier consolidated checkpoint. Machine-specific values in the working records under docs/execution/, docs/handoffs/ and BUILD_LOG.md are replaced by placeholders such as <vps-host> in this public tree.

BoardAgent is not a qualified electronic-signature service, a notary, legal advice, proof that a person understood a record, or a security certification. Your agent presents information; BoardAgent records exact information and confirmations. Each person remains responsible for reviewing the content and securing their agent and local copies.

What it does

• Keeps one organization and its boards, members, governance profiles, rules, documents, meetings, transcripts, minutes, votes, proxies, questions, submissions, proposals, and tasks in PostgreSQL.

• Applies role, board, recusal, confidentiality, lifecycle, and exact-resource checks on every MCP operation.

• Requires one-use, server-attested confirmation for binding human acts.

• Preserves append-only audit events, signed checkpoints, vote certificates, encrypted exports, backup receipts, and restore receipts.

• Supports built-in WebAuthn/TOTP authentication and pre-linked OIDC identities.

• Runs a separate least-privilege worker for notifications, exports, deadlines, checkpoints, retention of operational ephemera, and recovery jobs.

Related MCP server: agent-broker

Deliberate boundaries

• No server LLMs, embeddings, OCR, conversion, document extraction, or content-check API.

• Only canonical Markdown, plain text, and declared versioned JSON are accepted.

• PDF, PowerPoint, Word, images, scans, archives, and binary redlines are rejected.

• No governance UI and no email/SMTP workflow.

• The browser is for enrollment, authentication and onboarding attestation; board work and binding action confirmations use the person's supported MCP client.

• No physical purge of governance, content, audit, consent, or evidence records in v1.

• Webhooks are contentless wake-ups, disabled by default, and restricted against SSRF.

• A software client name is not identity. Deployment restrictions use exact server-issued client IDs or exact Client ID Metadata Document URLs checked through HTTPS and metadata validation. Metadata deadline and cleanup repairs have focused regression coverage; public DNS, HTTPS port 443 and actual provider acceptance remain unqualified.

The frozen implementation contract is BUILD_PLAN.md. Security and trust boundaries are in SECURITY.md; deployment is in DEPLOY.md.

Architecture

MCP client / human browser
          |
       HTTPS
          |
        Caddy
          |
  BoardAgent server ---- public certificate verifier
          |
   private backend network
          |
      PostgreSQL <---- least-privilege worker
          |                      |
   audit/evidence          exports/notices/jobs

Operator CLI ---- migrations, bootstrap, keys, verification, backup/PITR/restore

The supported v1 deployment is one organization on one Linux VPS, one BoardAgent server, one worker, PostgreSQL 18.6, and Caddy. Runtime containers run read-only, as non-root users, with dropped capabilities and separate database principals. Horizontal scale, multi-tenant hosting, public cloud control planes, and automatic failover are outside the frozen profile.

Exact development toolchain

• Node.js 24.20.0

• pnpm 11.24.0

• PostgreSQL 18.6

• Docker with Compose v2 for runtime and integration verification

Direct dependencies are exactly pinned. Do not silently substitute toolchain versions. The recorded provenance is under artifacts/provenance/.

Start here

Evaluate with Mining Exploration Co

The Mining Exploration Co fixture is a fictional charter and exercise pack for one nonvoting secretary and three equal-weight board members, with a separate setup administrator. Follow its setup instructions and inspect actual execution receipts before assuming an instance or account exists. Creating a fixture, installing a service, issuing an invitation, registering a passkey and completing onboarding are separate steps. Local and VPS installations need separate database state and credentials.

A secretary account does not automatically have a vote, company-administrator powers or a server login. The manuals explain the additional setup administrator and the supported handoff to the intended board seats. Use only this synthetic pack during the current evaluation. A scripted authenticator or automated ballot belongs to a test fixture; it cannot establish an actual person's acceptance.

Build and check a local checkout

Obtain an exact source checkout or reviewed source archive. With the exact versions listed above, run from its root:

corepack pnpm install --frozen-lockfile
corepack pnpm verify:phase0

verify:phase0 checks static integrity and provenance; it is not a running-system or database qualification. Some provenance/vendor/browser prerequisites are separate from dependency installation: follow tests/TESTING.md when a check identifies missing evidence. Do not skip a check to make setup pass.

For a disposable local installation, follow the Mining Exploration Co setup with reviewed .env.example values and synthetic data. Build the server/PostgreSQL images before starting services. The default server listens on loopback port 8787; it is not a browser governance interface. The production profile uses Caddy HTTPS and separate operator/runtime principals. Use the bootstrap procedure for its one-use operator command; do not run production bootstrap through the server's database role.

Keep enrollment links, activation codes, OAuth credentials, secrets and private operator inputs outside source control. Do not publish a deployment's .env, private login guide or captured account handoff with the example pack.

First agent journey

After your separate account is registered and activated, connect your agent to the exact HTTPS resource ending in /mcp supplied by the operator. A setup administrator and ordinary secretary are separate responsibilities; follow the account handoff in the administrator manual. A cautious first session is:

1. Connect and log in with your normal scopes; until your onboarding is current the server issues an onboarding:read token and says so in the token response. Call whoami, then list_my_boards.

2. Run onboard-boardagent, inspect get_onboarding, complete your own attestation; the next token refresh (within fifteen minutes) or reconnect carries your ordinary scopes.

3. Read get_my_board_snapshot, list_my_updates, and list_pending_actions.

4. Use strict read tools before any write. For a binding act, inspect the staged exact content and complete the server-driven confirmation yourself.

5. Rehearse an entitled read, then follow the role manual for a synthetic workflow. An eligible member chooses their ballot; the secretary opens the vote and follows its configured close mode. Keep automated fixture acts and actual human acts separate.

The full role-by-role guide, safe prompting rules, content formats, and confirmation workflow are in docs/AGENT_GUIDE.md. BoardAgent deliberately has no shared semantic “brain”: ADR 0005 defines why canonical shared records stay server-side while optional derived memory stays under each person's agent/client control.

Verification and release labels

The regression net has tiers T0–T10. The private-beta command runs deterministic tiers T0–T9; public release also requires independent external review at T10.

corepack pnpm verify:private-beta

The command must run against one unchanged source tree. A passing historical command is not evidence for later edits. Do not bless or alter regression-net state as part of a build. See docs/VERIFICATION.md for the 94 original security requirements and eight approved administrative additions, their proof status and exact tests, and tests/TESTING.md for test execution. A full private-beta or release run also writes gate3-manifest.json, evidence-ledger.json, outcome-comparison.md, and HANDOFF.md beside its result receipt. The legacy gate3 filenames remain for compatibility. These files collect candidate evidence; they do not invoke the retired Architect/Gate workflow or approve a release.

The Mining handover also needs a persistent local installation and a separately verified VPS installation, each with the intended people, reviewed charter, working custody and actual role-by-role acceptance. The owner publishes the reviewed repository to GitHub after checking its exact contents; a GitHub push does not qualify or deploy the product.

Contributing and reporting problems

Use synthetic reproductions and keep changes scoped to the stated defect. Preserve immutable migration history, generated registry contracts and failing evidence. Run focused checks, then the required full qualification on a clean final candidate. The build contract, build plan and verification instructions explain the repository requirements.

A useful nonsecurity bug report identifies the exact commit/image, environment, nonsecret request reference, expected result, observed result and minimal synthetic steps. Report vulnerabilities privately under SECURITY.md. Do not post real board records, invitation URLs, private keys or access tokens in issues.

Operations and security

• DEPLOY.md — supported topology, secrets, initialization, upgrades, and recovery.

• SECURITY.md — threat boundaries, reporting, residual risks, and known limitations.

• docs/AGENT_GUIDE.md — agent onboarding and safe operation.

• docs/SURFACE_REFERENCE.md — generated closed MCP, HTTP, CLI, resource, prompt, and event inventory.

• docs/runbooks/README.md — operator procedures and evidence expectations.

• docs/THREAT_MODEL.md — 63-threat control and proof matrix.

• docs/KNOWN_LIMITATIONS.md — release blockers, intentional boundaries, and residual-risk owners.

• docs/adr/ — accepted architecture decisions and tradeoffs.

No deployment, remote push, external-review contact, or sharing of real board data is authorized by Gate 2 alone.

BoardAgent is licensed under the MIT License. Report suspected vulnerabilities through the deployment's private security route described in SECURITY.md, never by posting board content or credentials publicly.