Corveil Docs

Appearance

Evaluating Corveil ​

This page is for a technical evaluator deciding whether to deploy Corveil — someone who does not have an account yet and wants to understand the system before committing to it. You can read it end to end without running a single command; nothing here asks you to provision anything today.

Every other page in these docs assumes an org is already running. This one does not. It answers three questions, in order:

  1. Where does it all live? — the deployment shape, what is inside the trust boundary, and what leaves your network.
  2. Where does the data flow? — one sensor from source to graph, the meeting-capture privacy boundary, and the gateway request path.
  3. What actions need to be taken? — the setup sequence, with a realistic sense of the effort in each step.

At the end, what you get today — and what you don't, stated plainly, so nothing on this page reads as a promise the shipped product does not keep.

Where does it all live? ​

Corveil is one Go binary run in two roles. Deployed via Terraform, it runs as containers on AWS ECS Fargate behind an internal, TLS-terminating load balancer, backed by a managed PostgreSQL database (RDS). There is no external service to trust with your data beyond the LLM providers you explicitly choose.

The two roles of that one binary:

RoleWhat it does
API / gateway (corveil serve)Terminates client LLM traffic, authenticates, applies guardrails and budgets, routes to a provider, and serves the dashboard, chat, and MCP surfaces.
Workers (corveil workers)Polls sensors, runs LLM extraction to build the knowledge graph, summarizes Insights, and aggregates session usage — all off the request path, on a background job queue.

Everything the product remembers — API keys, request logs, spend counters, the credential vault, and the knowledge graph itself — lives in that one Postgres database. Nothing is stored in a third-party analytics or telemetry service.

The trust boundary — what actually leaves your network ​

This is the part an evaluator cares about most, so it is worth being exact. There are only two ways data crosses the boundary of a Corveil deployment, and both are ones you configure:

  • Read-only sensor pulls, outbound to your own tools. A sensor reaches out to a source you connect — GitHub, Google Workspace, Slack, Jira, and so on — using a credential you store in the vault. Sensors read; they do not write back. (Action channels, which can write, are a separate, opt-in feature.) The data flows into your Corveil deployment, not out of it.

  • LLM calls, outbound to the providers you pick. When a client sends a request through the gateway, it is forwarded to one of three providers, and that is the only egress of prompt/response content:

    ProviderWhere it runsBilling
    OpenRouterSaaS relay (200+ models through one integration)The configured OpenRouter account
    Vertex AIGoogle Cloud (Gemini)The configured GCP project
    Bedrock GovCloudYour own AWS account — BYO-AWS, so discovery and inference run under per-org credentials and AWS bills you directlyYour AWS account

    Bedrock's bring-your-own-cloud model (BYO_BEDROCK.md) is the option for an evaluator who wants inference to never leave an account they control.

Provider keys are never handed to end users — that is the point of a virtual API key. Clients authenticate to the gateway; the gateway holds the real provider credentials.

Diagram A — system data flow ​

Two things feed the knowledge graph: the sensors you connect, and the gateway's own traffic. Both normalize into one raw event store (sensor_events), which a background worker turns into a graph of people, organizations, meetings, decisions, and the work they touch. That graph is then read by every surface — MCP clients, in-app chat, the daily Insights summaries, and the analytics dashboard.

Two consequences worth noting as you evaluate:

  • The graph is not instant. Extraction runs on a background cycle (roughly every 30 minutes), so entities appear after the first poll and the next extraction pass — not the moment a sensor is created.
  • The gateway feeds itself. The daily Insights summary is ingested back in as an always-on sensor, which is why gateway usage becomes part of the same graph your connected tools build. See Diagram D for the traffic side of that loop.

Where does the data flow? ​

Two flows matter: how one sensor's data reaches the graph, and how a client's LLM request moves through the gateway.

One sensor, end to end ​

Take the GitHub source as a concrete example. The path is the same shape for every sensor — only the source and credential type change.

  1. A credential is stored in the vault. You create a read-only GitHub PAT and POST it once to /api/credentials. The vault returns an id; the raw secret is never written into a sensor row and never echoed back.
  2. A sensor is created referencing that credential id (not the secret) plus a little config — an org or a repo list. One POST /api/sensors, or the Add sensor form.
  3. The worker polls the GitHub Events API, normalizes issues, PRs, commits, reviews, and comments into sensor_events, and stamps a signal on each.
  4. Extraction maps signals to entities — pull_request → a PullRequest, issue → an Issue, actors → People deduplicated against identities from your other sensors — and writes them into the graph with edges (AUTHORED, REVIEWED, RELATED_TO).
  5. The graph is queryable through the surfaces in Diagram A.

The per-sensor guides carry the exact credential type, config fields, and verification steps — this page does not duplicate them. Start at All Sources and pick the source you'd connect first.

Diagram B — meeting capture and the privacy boundary ​

Meeting capture is the flow evaluators ask the hardest privacy questions about, so it earns its own diagram. The single most important fact: what gets captured is decided upstream of Corveil, by your Google Workspace note-taking policy — not by sensor configuration. A meeting held without Gemini note-taking produces no transcript, no metadata, and no attendee list for either sensor to find.

The privacy boundary is the WS box: the decision of whether a conversation is recorded at all lives in Google Workspace, before Corveil is ever involved. The meeting-level opt-in is the privacy control. Everything below the gate is just a question of which read path — the Meet API across all members, or one watched Drive folder — picks up the resulting Doc.

For the full comparison, the per-organizer My Drive gap, and a recommendation, see Choosing a meeting-capture path.

Diagram D — the gateway request path ​

A client's LLM request flows straight through to a provider and back; the observability data forks off that path asynchronously, so logging and analytics never sit between the user and their response.

Reading it:

  • The response path is short. Auth, guardrails, budget, route, provider, post-guardrails, back to the client.
  • Analytics and spend fork off it. Each request writes a request_logs row whose metadata drives the analytics dashboard and whose cost feeds the spend counters the budget gate enforces. Request/response bodies are captured too, then aged out on a retention schedule (payloads nulled after ~7 days, rows after ~90) so the log table stays bounded.
  • Session usage rolls up separately. A background worker aggregates requests into llm_sessions, which is what the per-session usage views read.

What actions need to be taken? ​

Here is the setup sequence, in order, with a realistic sense of the effort. The point of listing it is so you can estimate the work, not execute it today — most of the real effort is provider-side credential provisioning, not anything inside Corveil.

  1. Provision the organization. An admin creates the org. Minutes — a one-time step.
  2. Invite your team. Members sign in through SSO (WorkOS) and are added to the org. Minutes. Who can do what once they are in — admin versus member — is the Roles & Permissions model.
  3. Store a credential in the vault. This is where the real effort is, and it is on the source side, not Corveil's. Minting a GitHub read-only PAT is a few minutes; setting up Google domain-wide delegation for the meeting and Drive sensors is an admin-console task that can take 30–60 minutes and may need a Workspace admin. Storing the result in the vault is one API call. See Credential vault for each type's shape.
  4. Create a sensor. Reference the credential id and set a little config (an org, a folder, a channel). One POST /api/sensors or one Add sensor form. Minutes per sensor.
  5. Verify it. Use Test connection or watch the first poll — then wait one extraction cycle (~30 minutes) before entities appear in the graph. Budget for this gap in a pilot; it is not instant.
  6. Mint a virtual API key. Under People & Access → API Keys. A team is mandatory on every key (it scopes spend and logs). Seconds.
  7. Point a client at the gateway. For LLM traffic, set the OpenAI-compatible base URL and the key — a drop-in change. For graph access, point an MCP client at /mcp. Minutes. The Client Setup guides cover CLIs, IDEs, SDKs, and desktop apps; the MCP reference covers the endpoint, auth, and the full tool catalog.

Where the time actually goes: steps 1–2 and 4–7 are minutes each. Step 3 is the one that varies — a GitHub token is trivial, Google domain-wide delegation is a real Workspace-admin task, and it is the same effort whether you are piloting or in production. Plan the credential work first; the rest is fast.

What you get today — and what you don't ​

Everything on this page is true of Corveil as shipped. A few honest edges, so nothing reads as more than it is:

  • Analytics and spend are captured for gateway traffic today — per-request logs, per-model and per-user rollups, and enforced budgets. That surface is real and in production.
  • The remote MCP transport does not emit per-tool audit rows or per-tool rate limits yet. Those fire on the in-app chat path but not on the external streamable-HTTP endpoint. If you need per-tool audit attribution during evaluation, use in-app chat; see the note on the MCP reference.
  • Fuller usage measurement is a build in progress, tracked in corveil#2424. Where this page describes usage/analytics, it describes what exists now; #2424 is the honest scope of what is still being built.

Where to go next ​