Corveil

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 and MCP surfaces.
Workers (corveil workers)Polls sensors, runs LLM extraction to build the knowledge graph, runs user workers, 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. (Workers, which can write via delivery channels, 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

    Choose Bedrock when inference should stay in an AWS account you control. You supply the credentials for that account; AWS bills it directly for catalog discovery and for each request.

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 ​

The knowledge graph is fed by the sensors you connect, plus the synthetic AI Chat capture (ai_chat) that records MCP tool calls. 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. Gateway proxy traffic is a separate product surface — auth, spend, analytics — and does not ingest into the graph via a sensor. That graph is then read by every surface — MCP clients, the Summaries dashboard, and the analytics dashboard.

One consequence 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. Per-person Daily and Hourly summaries are an output of that graph: User Workers write Summary entities that render under Corvus → Dashboards → Summaries. See Diagram D for the gateway request path — that traffic does not loop back into sensor_events.

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 sensor 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 Sensors 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. Connecting the identity provider, Directory Sync, and domain verification is SSO, SCIM & domain verification. 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 Corveil MCP reference covers the endpoint, auth, and the full tool catalog. To govern external MCP servers behind Corveil, see MCP Gateway.

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 or per-tool rate limits yet. See the note on the Corveil MCP reference.
  • Finer-grained usage measurement beyond those rollups is still being built. Where this page describes usage and analytics, it describes the logs, rollups, and budgets that ship today.

Where to go next ​

  • Getting Started — you have an org: connect Slack or Google Meet and see a first result in the graph.
  • Sensor Guides — per-source setup: credential, config, verify.
  • Choosing a meeting-capture path — the full Meet-vs-Drive decision behind Diagram B.
  • Credential Vault — the credential types every sensor references, and the effort behind step 3.
  • Client Setup and the Corveil MCP reference — pointing traffic and graph clients at the gateway.
  • MCP Gateway — governing external / third-party MCP servers (remote HTTP and vetted stdio) behind Corveil.