docs/AGENTS.md

Docs live here — one file per topic. Root AGENTS.md points here for the full catalog (cascading: this file loads only when working in docs/).

How to use

• Each ADR*.md is self-contained; read the ADR directly for design + status.
• Render-parity ledgers (ADR018, cli-compatibility-checklist.md) are evidence-backed.
• Security reviews form a chain ADR028 → ADR085 (see § Security lineage); read the latest for current residual.

Catalog — by topic

Vision, architecture, platform

• ADR008-vision.md — mission, AI-native pillars, roadmap
• ADR002-architecture.md — self-managed cluster, two layers, node pools
• ADR001-go-and-gitops.md — why product (Go) ≠ GitOps (platform infra)
• ADR003-control-plane.md — Postgres source of truth vs operator mechanism
• ADR019-infra-credentials.md — bootstrap credential inventory + trust chain
• ADR093-onbex-wildcard-tls.md — accepted (2026-10-30), implemented (2026-10-31) *.onbex.co fallback certificate renewed by cert-manager over DNS-01 with a Cloudflare token scoped to onbex.co; bex may call Cloudflare only to renew, never to serve; deploys stop carrying certificate PEMs (w4/441)
• ADR096-crashloop-suspension.md — accepted (2026-11-03) a service whose Ready condition stays False for 24h on a start failure (CrashLoopBackOff / HealthCheckFailing) is suspended with Render's stuck_crashlooping suspender and its workspace emailed; resume clears it (w2/m253)
• ADR097-build-sources.md — accepted (2026-11-03) Render Build Sources as a build-only carrier App (type build_source) whose image the operator copies into each linked service's own repository (blob mount, no Zot ACL change); bex-api fans a successful build out to auto-deploy services (w2/m254)
• ADR053-node-instance-types.md — Hetzner cx33/cpx32 policy

API, parity, Blueprint

• ADR006-bex-api.md — REST/GraphQL/MCP: one core, thin adapters, Render compat
• ADR018-render-parity.md — parity ledger (capability × surface)
• cli-compatibility-checklist.md — Render CLI compat matrix
• ADR049-render-yaml-parity.md — render.yaml canonical Blueprint contract
• ADR089-render-container-compatibility.md — accepted (2026-10-20) unchanged Render Docker example deployment: legacy aliases, the render-v1 container policy (Render's measured capability set), and multiple private TCP ports
• ADR020-identifiers.md — typed ids <prefix>-<xid> (tea-/srv-/cdm-)
• ADR032-environments.md — named env subsets of a Project

Auth, members, GitHub

• ADR012-auth.md — Ory Kratos + Hydra on CNPG; OAuth 2.1
• ADR027-sso.md — social OIDC via Kratos; enterprise SAML deferred
• ADR024-members.md — workspace members & roles, OpenFGA tuples
• ADR086-account-deletion.md — durable self-delete, workspace offboarding, credential cleanup
• ADR026-github-integration.md — self-hosted GitHub App, deploy keys
• ADR078-github-workspace-connections.md — workspace↔installation is N:N, each binding separately proved; why per-user credentials stay rejected
• ADR025-connect-an-agent.md — Claude/Cursor → /mcp over OAuth 2.1

App lifecycle & hosting types

• ADR004-app-deployment.md — deploy flow, health gating, revisions; node rolls hand single-instance services over via drain-guard (runbooks/drain-guard.md)
• ADR005-custom-domain.md — spec.hosts[], Traefik + cert-manager
• ADR007-restart-suspend-and-resume.md — lifecycle verbs
• ADR029-static-sites.md — static_site → object-store origin + static-server
• ADR038-cron-jobs.md — cron_job → CronJob, runAt/cancelRun
• ADR041-service-addresses.md — internal slug:port + public slug.domain
• ADR034-scalable-build-pipeline.md — BuildKit workers, concurrency
• ADR060-build-worker-reliability-and-performance.md — D1–D8 reliability/perf
• ADR009-postgresql-management.md — Database CR → CNPG
• ADR021-keyvalue-management.md — KeyValue CR → Valkey
• ADR082-persistent-disks.md — spec.disk → Hetzner volume PVC, $0.175/GB-mo, min 1 GB as on Render (Hetzner's 10 GB volume minimum absorbed, w8/215; reverses the stateless-first non-goal); arm its snapshots with runbooks/disk-snapshot-setup.md

Sandboxes, agents, mobile, SSH

• ADR014-sandboxes.md — E2B-compatible sandboxes over opensandbox
• ADR042-sandbox-cluster-substrate.md — multi-node OpenSandbox substrate, Kata/gVisor
• ADR044-sandbox-runtime-comparison.md — AgentENV vs OpenSandbox survey
• ADR035-ssh.md — instance SSH, gateway + Kubernetes exec bridge
• ADR054-open-in-zed.md — zed://ssh/ags-…@ssh.bex.co/workspace
• ADR047-cloud-coding-agent-sessions.md — sandbox-per-session, ACP driver, gateway grants; D5 per-workspace network tiers, registries open through the agent phase (2026-10-27)
• ADR051-agent-session-transcript.md — durable conversation history (headless recorder; completed-item model, w10/m16)
• ADR059-agent-sandbox-hibernation.md — Superseded 2026-10-25: agent-session hibernation retired; an idle sandbox is terminated after 2h, the transcript is kept, and a follow-up runs in a fresh sandbox (history: Active/Hibernated/Deleted + object-storage snapshots)
• ADR062-sandbox-credential-vault.md — BYO key via gateway proxy (mandatory)
• ADR065-agent-session-archive.md — archive/unarchive/delete, replay-only tickets
• ADR091-agent-model-pricing.md — accepted (2026-10-30) agent model pricing: provider cost × 1.30 via one agent_model_cost_microusd meter, Hobby pays per use, monthly USD spend caps, trust tiers (DigitalOcean-style rising charge thresholds, cap, concurrency) + settle-before-delete against non-payment, BYO key write path
• ADR094-coding-agent-mcp.md — proposed (2026-10-30) Cloud Agents MCP after a Devin MCP/API study: cloud-agents toolset at /mcp/cloud-agents, wait_agent_sessions, state + outcome, idempotent create, submit_result structured output, maxSpendUSD, bex.cloud_agents scope, completion webhooks
• ADR095-agent-attachments.md — proposed (2026-11-02) Cloud Agent attachments (Devin parity): bex-agent-attachments bucket, att- uploads streamed through bex-api, attachmentIds on create/steer, every dispatch copies inputs to read-only /attachments outside the repo, ACP resource_link + capability-gated image blocks, agent share_file outputs, presigned downloads on the storage origin, dashboard composer chips + Files tab, REST/GraphQL/MCP
• ADR098-agent-session-secrets.md — accepted (2026-11-05) Cloud Agent secrets (Devin parity): write-only workspace agent secrets (agent-sessions/<ws>/secrets/<NAME>) referenced by secretNames plus inline per-session secrets (deleted with the session), injected as env vars at every dispatch, driver redacts values and cheap encodings before any part is published, REST/GraphQL/MCP + dashboard (w9/m174)
• ADR099-agent-skills.md — accepted (2026-11-06) workspace skills for cloud agents (Devin parity, replaces Knowledge + Playbooks as Devin did): Agent Skills SKILL.md documents in agent_skills (skl-), admin-managed CRUD on REST/GraphQL/MCP, skills:[{name,arguments}] on create/steer, every dispatch copies enabled skills to /bex/skills linked into each engine's native skills folder plus an overlay index; repo skills stay engine-discovered (w9/m175)
• ADR101-agent-automations.md — proposed (2026-11-07) Agent Automations (Devin parity): an automation = triggers[] + a session template; phase 1 ships the schedule trigger (hour/day/week/once/custom cron, IANA time zone, ends-on). A scheduler loop in bex-api claims due rows with SKIP LOCKED, records (automation_id, fire_at), re-authorizes as the creator and calls Service.Create with an idempotency key; overlap skip, auto-pause after 3 failures, required maxSpendUSD on metered models; aut- ids, REST/GraphQL/MCP, /automations dashboard. Four open decisions need sign-off.
• ADR102-agent-child-sessions.md — accepted (2026-11-08) Agent child sessions (Devin parity): parent_session_id/root_session_id/depth on agent_sessions (parent FK ON DELETE SET NULL), depth ≤ 3 and ≤ 5 live children enforced in the insert transaction under a row lock on the parent; a child's spend counts against every ancestor ceiling (headroom checked at create and by the model-proxy mint), secrets inherit and may only narrow, can_create + can_operate on the parent, Cancel cascades to unfinished descendants, idempotent; in-sandbox spawn_session through ssh-gateway designed for t004. Spend and secrets defaults adopted by the worker, user may override.
• ADR090-agent-owned-delivery.md — accepted (2026-10-22) agent-owned delivery: the agent commits, pushes and opens its draft PR (gateway pull-request verb + bex stdio MCP tool), platform system-prompt overlay, evidence + credential-scrub machinery deleted
• ADR092-postgres-extension-supply.md — accepted (2026-10-29) managed Postgres extensions as on Render: one bex-built CNPG operand image per major carrying PostGIS, pg_partman, pg_duckdb, pg_ivm, pg_similarity and TimescaleDB; owner enables per database with CREATE EXTENSION through a closed allowlist (supautils or pgextwlist) for non-trusted extensions; one approved rolling restart to adopt the image.
• ADR048-mobile.md — supervision-first PWA + push, phone as mission control
• ADR087-mobile-role-views.md — proposed native views for five workspace roles; capability gates, notifications, and access changes
• bex-cli.md — CLI launcher release train (bex-cli/v*)

Observability, metering, billing, notifications

• ADR010-observability.md — logs (query + live-tail) + metrics
• ADR088-platform-observability-ui.md — Grafana at obs.bex.co (GitOps, monitoring ns), OIDC via Hydra, ops-workspace gate at consent; §6 = per-dashboard SLI/metric baseline, every-alert-gets-a-panel rule, and the tenant-facing surface coverage table (alert / scheduled probe / waiver per surface)
• ADR023-usage-metering.md — hourly rollup + GET /v1/usage
• ADR040-billing-metronome.md — Stripe Billing: usage_hourly → Customers/Subscriptions, BEX_STRIPE_SECRET_KEY
• ADR030-pricing.md — price sheet + estimatedCost (advisory; invoices = ADR040)
• ADR046-payment-onboarding-and-paid-gating.md — JIT payment-method gate (BEX_REQUIRE_PAYMENT_METHOD)
• ADR071-tenant-billing-credits.md — Stripe Credit Grants
• ADR052-notifications.md — deploy + audit → email / webhooks / push
• ADR075-user-onboarding.md — first-run checklist, card wall, demo-mode deferral

Secrets, backups, isolation

• ADR013-secrets.md — OpenBao tenant credentials, k8s auth tenants/*
• ADR016-sealed-secrets.md — SealedSecrets for infra creds
• ADR011-etcd-backup-restore.md — etcd snapshot → object storage
• ADR015-openbao-backup-restore.md — OpenBao Raft snapshot
• ADR031-platform-data-backup.md — consolidated backup policy
• ADR050-encrypted-platform-backups.md — age-encrypted backups, per-store creds
• ADR036-ca-rotation-runbook.md — K8s CA + admin-cert rotation
• ADR037-openbao-rekey-runbook.md — OpenBao root-token / Shamir rekey
• ADR022-tenant-isolation.md — east-west NetworkPolicy (superseded by ADR043 for boundary)
• ADR043-tenant-namespace-isolation.md — workspace = namespace isolation
• ADR074-workspace-scoped-artifact-identity.md — workspace-scoped Zot repos + S3 prefixes (W/A)

Deploy-from-chat, workflows, evals

• ADR017-deploy-from-chat.md — deploy-from-chat via Core.Create + HMAC webhook
• ADR033-workflows.md — Temporal orchestration (proposed, off-roadmap)
• ADR070-openchoreo-evaluation.md — reject OpenChoreo whole-platform adoption
• ADR039-operator-audit-and-platform-reuse.md — operator audit + reuse candidates
• ADR058-release-engineering.md — bex/vX.Y.Z lockstep, CLI bex-cli/v0.x until 1.0

Security review lineage (ADR028 → round 23)

Each entry is a codex-security triage; earlier rounds' residuals are re-confirmed in later ones. Read the latest (ADR085) for current posture.

• ADR081-security-review-harness-glm.md — harness architecture (proposed): reuse codex-security with a GLM model if possible, else mirror it on GLM 5.2; one harness at a time
• ADR028-security-review.md — round 0 audit (evidence-backed)
• ADR045-security-review-round3.md — round 3: host-hijack fix
• ADR055-security-review-round4.md — round 4: 12 findings, 6 fixed (F1/F4/F5/F8/F11/F12)
• ADR056-security-review-round5.md — round 5: 17 findings, 13 fixed
• ADR057-security-review-round6.md — round 6: 16 findings, 10 fixed
• ADR072-security-review-round7.md — round 7: 10 findings, 7 fixed (first zero highs)
• ADR061-security-review-round8.md — round 8: 12 findings, 5 fixed
• ADR062-sandbox-credential-vault.md — (hardened by ADR064, see above)
• ADR063-security-review-round9.md — round 9: 13 findings, 9 fixed
• ADR064-security-review-round10.md — round 10: 20 findings
• ADR066-security-review-round11.md — round 11: 10 findings, 7 fixed
• ADR067-security-review-round12.md — round 12: 10 findings, 7 fixed
• ADR068-security-review-round13.md — round 13: 9 findings, 7 fixed (sandbox-exec side door closed)
• ADR069-security-review-round14.md — round 14: 6 findings, auth-layer bex.api scope fix
• ADR073-security-review-round15.md — round 15: 8 findings, 5 fixed
• ADR076-security-review-round16.md — round 16: 13 findings, 12 fixed
• ADR077-security-review-round17.md — round 17: 15 findings, 11 fixed
• ADR079-security-review-round18.md — round 18: 10 findings (1 crit), 8 fixed
• ADR080-security-review-round19.md — round 19: 8 findings, 7 fixed (CI env gates, secrets CAS, metrics scoping)
• ADR083-security-review-round20.md — round 20: self-hosted CI runner risks accepted (persistent hosts, shared pool, fork-PR policy)
• ADR084-security-review-round22.md — round 22: dnR05P triage; 3 security fixes, 5 boundary/correctness hardenings, 2 accepted residuals
• ADR085-security-review-round23.md — round 23: 5PePz5 managed-Postgres credential resurrection fixed

Other docs: PRFAQ001-bex-v1-hosting.md, assets/ media.