On-prem connector

How it works

The connector is outbound-only. It opens a long-poll control channel to Codepanion and waits. When the agent needs your database, the query travels down that channel, the connector runs it locally — with the same read-only enforcement Codepanion applies everywhere (a read-only connection plus a transaction that is always rolled back, a 5-second timeout, and a 1,000-row cap) — and posts the result back. Your firewall stays closed.

Create a connector token

The connector authenticates with a token scoped connector — minted through the same API-token flow as your ingest key, with "scope": "connector". It can't upload code, and your ingest key can't open the connector channel: one credential, one job. The token value is shown once; rotation is the usual create-new-then-revoke-old.

POST /settings/ingest-tokens
{ "label": "datacentre-east", "scope": "connector" }

Run the connector

One container, three environment variables. Run it anywhere inside your network that can reach the database — Docker, Kubernetes, or a VM with Docker installed:

docker run -d --restart unless-stopped \
  --name codepanion-connector \
  -e CODEPANION_URL="https://api.codepanion.app/api" \
  -e CONNECTOR_TOKEN="<your connector-scoped token>" \
  -e CONNECTOR_DB_CONNECTION_STRING="Server=db.internal;Database=prod;User Id=codepanion_reader;Password=...;" \
  ghcr.io/codepanion-app/connector:latest

Use a dedicated read-only database user, exactly as you would for a direct connection — least privilege applies on your side too. SQL Server and PostgreSQL are both supported; the connector detects the provider from the connection string. The image is a hardened native build: a single static binary on a distroless base — no shell, no package manager, runs as a non-root user.

Point the agent at it

Mark a database environment as connector-mode and the agent routes that environment's queries through the channel instead of a stored connection string:

POST /settings/databases/prod
{ "mode": "connector" }

If the connector isn't running when the agent asks, the query fails fast with a clear "no connector connected" answer — nothing hangs, and the agent tells the support engineer what's wrong.

Network requirements

Outbound only. No inbound rules, no port forwarding, no VPN. If your egress is allow-listed, permit HTTPS (443) to:

api.codepanion.app                    # the control channel
ghcr.io                               # pulling connector images
pkg-containers.githubusercontent.com  # GHCR's blob storage (image layers)

The two registry hosts cover both your initial docker pull and the connector's future automatic updates.

What we can and can't reach

Through the connector, the agent can do exactly two things: run read-only queries expressed in Codepanion's structured query language, and read your database schema (tables, columns, keys, indexes). That's it. It cannot write — the connector wraps every query in a read-only connection and a transaction that is always rolled back. It cannot run arbitrary SQL — queries arrive as a structured definition that is compiled and parameterised locally, against your actual schema. And it cannot reach anything else on your network: the connector connects to the one database you configured, and nothing in the protocol can change that from our side.

Updates

The connector reports its version on every heartbeat, so we can see who is running what. Today, updating is a normal docker pull + restart (or your orchestrator's rolling update).