How it grows

git clone https://github.com/paracoding-ai/paracoding-oss.git
cd paracoding-oss
gcloud config set project YOUR_PROJECT_ID
bash install.sh

From a clone it is bash install.sh, because files committed through GitHub's web UI carry no executable bit. The release tarball on the v10.0 release page keeps its modes, so from there it is ./install.sh.

1. 1

   Enable the APIs

   Cloud Run, Cloud Build, Artifact Registry, Firestore, Cloud Storage, Secret Manager, Cloud KMS, IAP and the Vertex surface it needs. Enabling an API is idempotent, so a re-run is cheap and safe. If billing is not enabled on the project, this is where you find out — immediately, not three minutes later.

2. 2

   Create the Firestore database and the bucket

   Firestore holds the durable state: work items, the memory graph, the journal, history, and the git metadata — refs, HEAD, config, .git/index, packed-refs and the working tree. Cloud Storage holds the git objects, every one of them sealed in a PCV1 envelope before it is written. Between the two there is no disk anywhere that has to survive a restart.

3. 3

   Create three service accounts

   One per surface, and they are deliberately not interchangeable. The console identity talks to IAP-fronted state. The MCP identity serves tools over OAuth 2.1. The executor identity runs commands and has zero datastore access — it cannot read the journal, cannot read work items, cannot read the memory graph. It trusts exactly what a signature covers and nothing else. Three identities is what turns "a leaked key leaks a role, not the system" into a mechanism rather than a slogan.

4. 4

   Mint the keys, put the secrets in Secret Manager

   Cloud KMS gets the asymmetric signing key for job approvals and the key-encapsulation key for encryption at rest. Session secrets, OAuth client material and service credentials go into Secret Manager and are mounted at runtime — not baked into the image, not passed on a command line, not left in an env var in a build log. The executor is handed only the public half of the signing key: it verifies a signature it could not produce.

5. 5

   Build one image, deploy the surfaces

   Cloud Build produces a single container image. That image is deployed as the IAP-fronted console, as the OAuth-guarded MCP server, and as the executor. Which routes each service answers is decided by a 90-entry route table enforced at build time — a route landing on neither service throws at boot, rather than 404-ing quietly in production six weeks later.

6. 6

   Test itself, then exit with a verdict

   The installer does not finish by printing a URL and wishing you luck. It exercises what it just built: the surfaces answer, the identities can do what they must and cannot do what they must not, the tool surface loads, the signing path signs. If any of that fails, install.sh exits non-zero. A green install is a claim the script is willing to stake its exit code on.

Why the self-test matters more than it sounds. The same discipline runs through the smoke suite: every assertion has a seeded defect that must flip the verdict. A check that cannot fail is worse than no check, because it produces confidence without producing information.

No prompt is left. Step 6d/10 seeds exactly one allowed Google account — the account running the install — and asks for nothing, so the default run takes no keyboard input from start to finish. Additional accounts are given up front with --approver-emails a@b.com,c@d.com (or PC_APPROVER_EMAILS= in the environment; the flag wins), or added later in the console Settings under Allowed accounts.

Said plainly: there is no per-job passkey approval in the default install. A staged job is signed and executed in the same call, and the journal records who staged it, the command, and what it returned. If you want a hard stop before execution, the switch is PC_AUTO_APPROVE=0 — see the table below and the security page.

1. 1

   The work item is posted

   From the Flow Hood, from an MCP client, or from another strain. It is a Firestore document with an owner, a role, a state and a body. It exists before any model has seen it, and it still exists if no model ever does.

2. 2

   A strain claims it

   The strain acts under its own identity on a Vertex-backed model bus. Everything from here is attributed to that role: tool calls, file writes, git commits, journal entries. If it needs another strain it asks over A2A (ask_agent → answer_message → check_answer) rather than assuming a capability it does not have. Each role publishes an agent card at /agents/{role}/.well-known/agent-card.json.

3. 3

   It works through the tool surface

   ~55 MCP tools: read and write files, query and extend the memory graph, commit and push to serverless git, call GCP APIs, post and complete work items, append to the journal. Git pushes are classified, not retried — ALREADY_EXISTS, NOT_FOUND, STALE — and there is no force push to reach for when one is rejected.

4. 4

   It stages a privileged job

   When the work needs a real command, the strain stages it. Elevation is bound to one job ID plus one command digest. Edit the command after staging and the signature no longer matches it, so it is refused. The digest is the contract, not the intent.

5. 5

   It is signed, then executed

   Cloud KMS asymmetric-signs it. The executor verifies that signature with the public half, checks the approved_sha256 pin, enforces the staleness window so an old signature cannot be replayed, takes an atomic single-use claim so the job runs exactly once, and executes in a PATH-jailed subprocess under a hard timeout. Results are create-only objects — an executor that cannot overwrite a result cannot quietly rewrite history. With the shipped PC_AUTO_APPROVE=1, staging and execution happen in the same call. With PC_AUTO_APPROVE=0, the job lands in pending and never runs.

6. 6

   The journal records it

   Who staged it, the exact command, and what it returned. The journal is in your Firestore, in your project, encrypted at rest, readable by you and by the next strain that needs to know what already happened. This is the artefact the whole design exists to produce: not a permission prompt — a record.

The boundary is the point. Paracoding never resells you tokens and takes no margin on either side of that switch. It routes to a bus you configured, with credentials you supplied, against an account you own. If you hit a usage limit on the personal plan, that is between you and your vendor — and it costs you nothing here, because the state was never in the model.

Memory graph, journal, history, files and git all live in your project, encrypted at rest. A model is a renderer over that state, not the owner of it. So changing the model — a new plan, a different vendor, a fresh window after a usage limit — is a configuration change, not a loss.

# the bootstrap paste: give a fresh client the address of the farm and an identity,
# and the strain resumes with its full history intact
{
  "mcp_endpoint": "https://mcp-<hash>-<region>.a.run.app/mcp",
  "role": "builder",
  "oauth": { "client_id": "<from Secret Manager>", "scope": "paracoding.tools" }
}

Paste that into a new client, authenticate, and the first thing the strain does is read its own journal and memory graph. It knows what it was doing. It knows what it already tried. It knows which commands it ran and what they returned, because it can read the record instead of being handed a summary of it. The start page has the exact paste your install prints, and the strain settings panel in the console holds the session pastes, key rotation and allowed-account controls.

This is also the disaster answer. Lose the laptop, lose the browser profile, lose the vendor: the farm is in your GCP project, and the way back in is a Google login and a paste. Nine codified lockout classes exist specifically to block the changes that would destroy that way back in.

bash workstation.sh              # asks: none, linux or windows
bash workstation.sh linux        # non-interactive, scriptable
bash workstation.sh windows