Co-VibeDocs

Engineering

GCP Production Path#

Co-Vibe will run at https://co-vibe.dev on Google Cloud after the production database and security gates are complete.

This file is a deployment preparation note, not a deploy log. Do not deploy from this repo until the human security-review pause is complete.

Current Decision#

  • Product name: Co-Vibe is the public-facing brand.
  • Domain: co-vibe.dev.
  • Compute target: Cloud Run container.
  • Production database target: Cloud SQL for PostgreSQL.
  • Local/dogfood database: PostgreSQL. Use a local Postgres container or a managed test database.
  • Auth: WorkOS AuthKit stays the hosted auth path.

The repo now has PostgreSQL schema initialization, tenant/workspace row-level-security policy generation, and a PostgreSQL runtime bridge behind getDb() for the existing repository surface. The bridge is a transition layer; the long-term cleanup is to convert repositories to native async pg calls.

GCP Shape#

Use one Google Cloud project for the first production environment unless there is a compliance reason to split projects.

Recommended first resources:

  • Cloud Run service: co-vibe.
  • Artifact Registry repository for the container image.
  • Cloud SQL for PostgreSQL instance in the same region as Cloud Run.
  • A Cloud Run service account with the Cloud SQL Client role.
  • Secret Manager entries for WorkOS, cookie, database, and optional model keys.
  • External HTTPS entry point for co-vibe.dev.

Required database env for the PostgreSQL path:

bash
COVIBE_DATABASE_BACKEND=postgres
# Non-superuser, non-owner Cloud SQL role — subject to row-level security.
DATABASE_URL=postgres://covibe_app:...@/covibe?host=/cloudsql/<conn>
# Owner role used only for init + provisioning (db:postgres:init or auto-init).
COVIBE_POSTGRES_ADMIN_URL=postgres://covibe_owner:...@/covibe?host=/cloudsql/<conn>

Initialize a fresh PostgreSQL database with:

bash
npm run db:postgres:init

When COVIBE_POSTGRES_ADMIN_URL is set, npm run db:postgres:init connects as the owner to create the schema and seeds, then idempotently provisions the non-superuser DATABASE_URL role with usage on schema public and select/insert/update/delete on all tables (plus default privileges for future tables). The runtime app then connects only as that role, so Postgres RLS is enforced. In Cloud SQL, create the owner as a superuser-equivalent (or the Cloud SQL admin role) and the app role as a plain LOGIN role.

Verify the generated schema and tenant isolation policies locally with Docker:

bash
npm run smoke:postgres
npm run smoke:postgres:runtime

Google's Cloud SQL guidance for Cloud Run requires the service to be connected to the Cloud SQL instance, commonly with --add-cloudsql-instances, and the Cloud Run service account needs the Cloud SQL Client role. Google also recommends keeping Cloud SQL and Cloud Run in the same region to reduce latency and cross-region risk.

For co-vibe.dev, prefer a global external Application Load Balancer in front of Cloud Run for production custom-domain traffic. Google documents Cloud Run domain mapping as preview and not recommended for production services.

References:

Blockers Before Deploy#

  1. Run npm run db:postgres:init with COVIBE_POSTGRES_ADMIN_URL (owner) and DATABASE_URL (non-superuser app role) set, so the schema is created by the owner and the runtime app role is provisioned with least privilege.
  2. Run npm run smoke:postgres and npm run smoke:postgres:runtime.
  3. Store profile uploads outside the container, likely Cloud Storage.
  4. Keep pre-rename MCP, env, and package names out of the first public launch path; all new setup paths must use Co-Vibe names.
  5. Run the repo security gate and both external security-review sessions.
  6. Add https://co-vibe.dev/callback to WorkOS Redirects.
  7. Run the strict handoff gate only after the permanent domain is live:
bash
npm run readiness:handoff -- https://co-vibe.dev

Security-Review Pause#

Before any GCP deploy command is run, stop and ask the human operator to run:

  • Claude Code security review.
  • Codex security review in a separate session.
  • Any Cursor-side review the team wants for the local companion path.

Only continue to GCP deployment after those reviews are complete and their findings are either fixed or explicitly accepted.

Agent Connection Canary#

After deployment and security review, test each supported agent path against https://co-vibe.dev with a fresh MCP token created in Settings.

Claude Code:

  • Run the Agent Setup install command.
  • Confirm .mcp.json exposes the server.
  • Confirm .claude/settings.json contains the session hooks.
  • Start Claude Code and verify covibe_session and telemetry usage events.

Codex:

  • Run npm exec -- covibe-local doctor --base-url https://co-vibe.dev.
  • Run npm exec -- covibe-local watch --base-url https://co-vibe.dev --once.
  • Verify repo snapshot data is stored without file contents.
  • Verify Codex/provider telemetry JSON can flush through .covibe/telemetry.

Cursor:

  • Run npm exec -- covibe-local setup and confirm .cursor/mcp.json exposes the server token-safely and .cursor/hooks.json carries the lifecycle hooks.
  • Run a Cursor agent session and verify covibe_session start/snapshot/end events plus swept usage counters.
  • Verify the server stores counters and a payload hash, not prompts or transcripts.

The final proof is a successful npm run readiness:handoff -- https://co-vibe.dev.

View as .md