paracoding-oss

<!-- Paracoding.AI Agentic Harness — Apache License 2.0 SPDX-License-Identifier: Apache-2.0 See LICENSE and NOTICE for terms. Copyright 2026 Seaside Mushrooms LLC. --> # Paracoding **A supervised AI agent fleet that deploys into your own Google Cloud from one repo.** **AI proposes. A human commits.** [](LICENSE) [](https://github.com/paracoding-ai/paracoding-oss/releases) [](#architecture)  **The security record is published, not available on request.** [The launch security review](security/security-review-v2-launch-2026-07-27.pdf) is eleven pages: the control plane, the passkey gate, the MCP harness, the data lake, the runners, the deploy chain, and which of the 27 original findings closed and with what proof. [Zero Is a Claim](security/security-thesis-2026-07-27.pdf) is the three-page thesis behind it. Both are dated 27 July 2026 and were written before launch, not after someone asked. More in [security/](security/) and [SECURITY.md](SECURITY.md). --- ## What this is Paracoding is a small, always-on control plane and a roster of role-scoped AI agents that run **in your Google Cloud project, under your billing, behind your passkey.** Agents propose work. Nothing consequential happens until you approve it with a hardware-backed passkey on your own device. v2 is **serverless by default.** The whole fleet — control plane, board, journal, approval gate, agent routing — runs on Cloud Run, Firestore and Cloud Storage. There is no server to patch and nothing idling on your bill. The remote Linux desktop from v1 is now an **optional add-on** (`provision-workstation.sh`), not a prerequisite. ## Why it's safe to point agents at real infrastructure Most "autonomous agent" projects ask you to trust that the agent won't do something catastrophic. Paracoding is built on the opposite premise: > **An autonomous agent must never be able to take a consequential action on its own.** Every privileged operation is *staged* by an agent and *committed* by a human. There is no unattended path to root. An agent that is confused, misled, or prompt-injected still cannot change production — because the approval step is a physical action no agent can perform. | Control | What it does | |---|---| | **Human-apply gate** | Stage → human approves with a WebAuthn passkey → run. Self-approval and unattended runs are rejected by construction. | | **Fails closed** | With no strong `WA_SESSION_SECRET`, no gate session can be issued or verified. With an empty approver list, god-mode is denied outright. | | **Least privilege** | A dedicated control-plane service account — never the default compute/Editor SA. | | **Keyless by default** | Workload identity (ADC). Gemini runs through Vertex OAuth with **no API key at all**. | | **Secrets never in the repo** | All secrets are generated into Secret Manager by `deploy.sh` and wired via `--set-secrets`. No literals in this tree. | | **Append-only audit trail** | Every action and decision is written to a durable journal. | | **Reproducible from source** | The deployed fleet rebuilds from this repository. | ## Zero-key by design You can stand this up with **nothing but a Google Cloud project.** Gemini is reached through Vertex with an OAuth bearer token — there is no AI Studio key to create, paste, or leak. Bringing your own Anthropic key is **supported and encouraged**, not a downgrade: set `ANTHROPIC_API_KEY` and the Claude lane lights up alongside Gemini for two-brain routing. Zero-key is the floor, not the ceiling. ## v1 is still in this repository v1 was a different shape: an always-on hardened Linux desktop you remote into, provisioned with systemd units, an nginx edge and a Python MCP server. Those files have **not** been deleted — `agents/`, `docs/`, `jobs/`, `mcp/`, `nginx/`, `scripts/`, `systemd/`, `requirements.txt` and the [Security Whitepaper](ParacodingSecurityWhitepaper.pdf) are all still here, and the `1.1` tag pins that tree exactly as it shipped. v2 is not a file-by-file replacement of it. It is a serverless rebuild that lives in `src/` and installs with `./install.sh`. **If you are starting today, start with v2.** The v1 material is kept for provenance, for the threat-model write-up, and for anyone who wants the desktop-in-the-loop setup — which v2 still supports as the optional `provision-workstation.sh` add-on. ## Architecture - **Cloud Run** control plane (the fleet's brain: board, journal, gate, routing) - **Firestore** for the shared board, journal and docs pages - **Cloud Storage** data lake - **Vertex Gemini**, plus optional BYO Anthropic Claude, with dual-bus routing - **WebAuthn passkey gate** that fails closed - **Optional**: a Shielded-VM Linux workstation (`provision-workstation.sh`) for when you want a real desktop and a real browser in the loop ## The four agents A fresh install seeds exactly four strains (`STRAIN_SEED` in `src/mcp-oauth.ts`) — no more, no less. Each ships a plain-markdown greeting you can read right here without deploying anything: - **[fleet-advisor](src/greetings/fleet-advisor.md)** — fleet-wide status, dispatch, and the gate. The identity the human OAuth connector binds to by default. - **[fleet-infra](src/greetings/fleet-infra.md)** — build and deploy proposals, staged to the gate. - **[fleet-security](src/greetings/fleet-security.md)** — review and findings. Advisory only. - **[fleet-publisher](src/greetings/fleet-publisher.md)** — owns the internal docs site. Every greeting lists **only** capabilities that are actually wired and running. Once deployed, the same text renders live at `/greeting/<role>` and is prepended to the agent bootstrap, so it can never drift from what is in this tree. ## Quickstart You need a Google Cloud project and the `gcloud` CLI. Then: ```bash ./install.sh <PROJECT_ID> [REGION] ``` That provisions the service account, creates the secrets, deploys the control plane, and prints the URL of your gate. Register a passkey, and you are the only person who can approve anything. Configuration templates live in [`.env.example`](.env.example) — every entry is commented out, and real secret **values** never belong in it. ## Honest posture This project is deliberately precise about what it earns and what it does not claim. - **Not independently audited.** The design was threat-modeled before release and the findings are written down with their fixes, but no third party has reviewed it. It makes no compliance claims. - **`install.sh` has not been run end-to-end by anyone yet.** v2 is fresh. Read it before you run it, and expect to find something. Please open an issue when you do — that is the single most useful contribution right now. - **Role does not separate lanes today.** Identity is token-bound: one connector token maps to exactly one role. The reference deployment provisions a single account-level connector, so every interactive session authenticates as the same token and the same role. Per-agent identity exists only for runners that can mint a service-account OIDC token. [SECURITY.md](SECURITY.md) states exactly what this does and does not isolate. - **Fails closed ≠ refuses to boot.** A missing or weak secret is logged with `console.error` and disables the affected feature; the service still starts and still serves. Do not rely on a crash to tell you the deployment is misconfigured — read the logs. - **Not every route is gated.** `/support` and the `/api/` routes in `src/control-plane.ts` are public by design. [SECURITY.md](SECURITY.md) lists them. - **`MCP_PUBLIC_URL` must be pinned.** Left unset, the OAuth metadata falls back to the request's `Host` header, which is attacker-controllable. This is shipped as it runs, disclosed rather than quietly patched before review. - **A single-operator deployment concentrates trust in one operator.** That is a real trade-off, stated plainly rather than hidden. Before you publish a fork, read [PUBLISH-GATE-LIMITS.md](PUBLISH-GATE-LIMITS.md): the pre-publish gate is a **lint, not an audit**, and a green run does not mean a tree is safe to publish. ## Documentation - [SECURITY.md](SECURITY.md) — full security posture, including a frank list of what this tree does **not** protect you from. - [Security Whitepaper (PDF)](ParacodingSecurityWhitepaper.pdf) — the v1 formal threat model: STRIDE-per-element, a NIST SP 800-30 risk register, MITRE ATT&CK mapping, and all thirteen findings (F1–F13) with their verified fixes. Written against the v1 architecture; the human-apply gate, least-privilege and audit-trail properties carry forward. - [PUBLISH-GATE-LIMITS.md](PUBLISH-GATE-LIMITS.md) — what the pre-publish gate does and does not catch. - [CONTRIBUTING.md](CONTRIBUTING.md) — how to propose changes. - [TRADEMARKS.md](TRADEMARKS.md) — name and mark usage. ## License Apache License 2.0. See [LICENSE](LICENSE) for the full text and [NOTICE](NOTICE) for attribution and third-party components. You are free to use, modify, deploy, fork and redistribute it, **including commercially.** Nothing you can pay for unlocks a feature, removes a restriction, or changes your rights under the License. Attribution beyond what Apache-2.0 section 4 requires is appreciated but not required. The bundled ad panel has an optional ad-free switch (`src/support.html`). It is free, instant and entirely local — it sets a cookie in your own browser, with no key, no install ID, no phone-home and no check on startup. It is not a licence of any kind, and you can also just delete the ad markup from your copy. --- *Everything gated · least-privilege · logged · reproducible from source.* &copy; 2026 Seaside Mushrooms LLC.