Connections

The connector catalog

Create connections from the dashboard's Connections page, scoped to your environment.

Authentication with secret:// references

Credentials never live in the dashboard in cleartext. Instead of a password you store a secret:// reference, and the agent resolves the real value at execution time using its own ambient identity — never a per-connection key baked into config. A reference can be a whole field or embedded mid-string:

secret://env/DB_PASSWORD
secret://aws-sm/prod/orders-db?key=password
secret://azure-kv/my-vault/orders-db
secret://gcp-sm/my-project/orders-db

• secret://env/NAME — an environment variable on the agent host (via its keyring → env chain).
• secret://aws-sm/… and secret://aws-ps/… — AWS Secrets Manager and SSM Parameter Store.
• secret://azure-kv/… — Azure Key Vault.
• secret://gcp-sm/… — GCP Secret Manager.

Worked examples

A REST API. Create a connection of type HTTP API, set the base URL (e.g. https://api.internal.example.com/v1), and pick the authentication your API uses — None for an open endpoint, or a bearer token / API key stored as a secret:// reference. Leave Allow private networks off for a public endpoint; turn it on to reach an API on your internal network. Functions built on it then use relative paths like /products or /products/{'{{'}id{'}}'}.

A database on the agent's host. Create a PostgreSQL connection pointing at where the agent reaches the database — for a database running on the same host as the agent that's host 127.0.0.1, port 5432, plus the database name, username and password. Turn Require SSL off only if the database has no TLS, and enable Allow private networks so the agent may dial a private/loopback address. The password is stored encrypted (or as a secret:// reference) and only ever resolved on the agent at call time.

Because the agent — not the backend — dials the connection, the host you enter must be resolvable from the agent's network, not from ConnXL.

Connecting Supabase

Supabase hosts plain Postgres, so the Supabase connector speaks the Postgres wire protocol directly to your project's database. Two things differ from a self-hosted Postgres:

• Host and user. For a direct connection use db.<project-ref>.supabase.co, port 5432, user postgres. Going through Supabase's connection pooler instead, the user becomes postgres.<project-ref> and the port 6543 — the pooler is the right choice when many agent replicas share one project.
• SSL mode. Supabase requires TLS but its CA is not in stock trust stores, so the connector defaults to require (encrypted, certificate not verified). If you install Supabase's CA certificate on the agent host you can raise it to verify-full.

The database password lives in your Supabase dashboard under Project Settings → Database; store it as a secret:// reference like any other credential.

To reach the same project through Supabase's REST API instead, with Row-Level Security applied per signed-in Excel user, see Row-Level Security (token exchange).

Test a connection

Use Test connection in the dashboard to check a source is reachable. The probe runs on the agent, from inside your network — an HTTP request, a SQL SELECT 1, or a cache scan. The backend never dials your data sources itself, so this works for sources that aren't reachable from the public internet. Source families without a live probe report "saved untested" rather than failing.

You can manage connections from your add-in's Connections page once an add-in is selected.