Connections overview
What connections are, the three kinds, what saving checks, and how connections are used across Compass.
A connection is a saved, reusable link to an external service, with its credentials and settings stored securely. You create a connection once and then reference it from any agent, workflow, or dataset in the project — so secrets live in one place, not scattered across your work.
Connections are managed under Studio → Connections. Each one belongs to the project you create it in, and everything you build in that project can use it. To use the same service in two projects, create a connection in each.
The three kinds
Every connection is one of three kinds, depending on what it links to.
Providers
Model providers — the models an agent thinks with, the embedding models datasets index with, and OCR for scanned documents. Anthropic, OpenAI, LM Studio, Azure Document Intelligence.
Integrations
Services and data your AI can act on. Postgres, S3-compatible storage, Qdrant, or any API you bring with an OpenAPI spec.
Gateways
An optional proxy that provider and API calls are routed through for monitoring and policy. Apigee.
The Connections page
The page is a catalog of every connection type available to your project, with tabs — All, Providers, Integrations, Gateways — and a search box along the top. Each type is a card showing how many connections of that type the project has.
Click a card to open its panel. The panel lists the project's connections of that type, with New connection at the top. Integrations also have a Tools tab listing every action the integration offers, with its inputs and outputs.
Each connection row shows its name and status, and for providers, the model the
connection runs and what that model can do — Generation, Embedding (with
its vector size, such as 3072d), or OCR. The … menu on a row holds
Edit and Delete.
Config and credentials
When you set up a connection, you fill in two kinds of fields:
- Configuration — non-secret settings such as a base URL, a bucket, or a host. These are stored as plain values and shown whenever you edit the connection.
- Credentials — secrets such as an API key, token, or password. These are encrypted at rest and never shown again after you save. See Editing a connection for how they're handled when you make changes.
Required fields and credentials are shown first; optional settings are tucked under an Advanced section.
Authentication
Each service authenticates in whichever of these ways it supports:
| Auth type | What you provide | Used by |
|---|---|---|
| API Key | A key or token. For custom OpenAPI integrations, optionally the header it's sent in (default X-API-Key). | Every provider, Qdrant, custom OpenAPI integrations |
| Username & Password | A user and password. | Postgres |
| Access Key | An access key ID and secret access key, plus a session token for temporary credentials. | S3 |
| None | Nothing — the service needs no credentials. | S3, Qdrant, custom OpenAPI integrations |
When a service offers only one option it's selected for you; when it offers several, pick one under Authentication.
Creating a connection
Open the type
Under Studio → Connections, click the card for the provider, integration, or gateway you want, then New connection.
Name it
Give the connection a clear Connection name, like "Postgres — Reporting". Names are unique per project.
Work through the steps
The form is a short series of steps you complete in order — Continue moves to the next, and the last reads Done. Depending on the type: an optional Gateway, Authentication, Configuration, and for providers the Model and Spend & cost steps.
Create
Once every step is done, click Create connection. A toast confirms the save — or shows why it failed.
What saving checks
Saving a connection is also how Compass checks it. What gets checked depends on the kind:
| Kind | Checked at save |
|---|---|
| Providers | The credentials are checked live against the provider — for an embedding model, with one embedding call. If the provider can't be reached, the save fails. The check also records what the model can do. See what saving records. |
| Postgres | The database's schema is read. If the database can't be reached, the save fails. |
| S3, Qdrant, custom OpenAPI | Not checked. A wrong key or address shows up the first time something uses the connection. |
| Gateways | Required fields only — there's nothing to call until traffic flows through. |
There's no separate Test button. To re-check a provider connection, edit it and save again.
Connection status
The dot beside each connection shows whether it's active. Active connections read Connected. A connection that's been switched off reads Error: it's hidden from model, integration, and tool pickers, and anything that still uses it fails with an error that names it. Switching a connection off is done from the API or CLI.
How connections are used
Connections are what your work points at when it needs the outside world:
- Agents — an agent's model is a provider connection. See Building an agent.
- Components — the Embeddings component uses a provider's embedding model, and the Document Parser uses an OCR connection for scanned pages. See Node types.
- Integration nodes and agent tools use an integration connection to call a service or query data. See Giving agents tools.
- Datasets use an embedding connection to index, an OCR connection to read scanned pages, and storage connections as sources. See Datasets.
- Compass Chat runs on a provider connection you pick in the composer. See Compass Chat.
- Gateways, when attached to a connection, sit in front of its calls.
Because the credential lives on the connection, you can swap or rotate it without touching any agent or workflow that uses it — including live deployments. A deployment can also be pointed at a different connection without redeploying; see Managing connections.
Who can manage connections
Admins and Developers can create, edit, and delete connections. Reviewers can see them, but not change them. See Members & roles.