Relay

The Relay is an on-premises agent that bridges corporate databases to Concourse. Database credentials never leave the relay host. The relay connects outbound only — no inbound firewall rules are required.

How it works

1. The relay opens an SSE (Server-Sent Events) connection to Concourse to receive query jobs.
2. When a job arrives, the relay executes the SQL against the target database.
3. Results are POSTed back to Concourse over HTTPS.

Concourse never stores database credentials. The relay holds them locally in its configuration file.

Setup

Step 1: Register the relay in Concourse

Create a relay via the admin panel or the API:

curl -X POST http://localhost:8080/api/v1/relays \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Office Relay"}'

The response includes a relay id and token. Save the token — it is shown only once.

Step 2: Create the relay configuration

Create a relay.yaml file:

relay:
  name: ${RELAY_NAME:-Office Relay}
  concourse_url: ${CONCOURSE_URL}
  token: ${RELAY_TOKEN}

connections:
  - id: finance-prod
    name: Finance Production
    dialect: postgres
    host: ${DB_HOST}
    port: 5432
    database: finance
    username: inboard_svc
    password: ${DB_PASSWORD}

  - id: analytics
    name: Analytics Warehouse
    dialect: postgres
    host: analytics-db.internal
    port: 5432
    database: warehouse
    username: inboard_ro
    password: ${ANALYTICS_DB_PASSWORD}

Step 3: Run the relay

docker run -d --name relay \
  -v ./relay.yaml:/etc/inboard-relay/config.yaml:ro \
  -e CONCOURSE_URL=https://your-concourse.example.com \
  -e RELAY_TOKEN=rl_xxx \
  -e DB_HOST=db-prod.internal \
  -e DB_PASSWORD=secret \
  ghcr.io/inboard-ai/relay:latest

Step 4: Verify

Check that the relay appears as online in the Concourse admin panel, or query the API:

curl http://localhost:8080/api/v1/relays \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Connection configuration

Each connection in the relay config has the following fields:

Field	Type	Required	Description
id	string	Yes	Unique identifier. Must match what Concourse expects.
name	string	Yes	Human-readable name shown in the inboard app.
dialect	string	Yes	Database type: postgres, mysql, mssql, sqlite.
host	string	Yes	Database hostname or IP address.
port	integer	Yes	Database port.
database	string	Yes	Database name.
username	string	Yes	Database username.
password	string	Yes	Database password. Supports ${VAR} interpolation.

Docker Compose

services:
  relay:
    image: ghcr.io/inboard-ai/relay:latest
    volumes:
      - ./relay.yaml:/etc/inboard-relay/config.yaml:ro
    environment:
      CONCOURSE_URL: https://your-concourse.example.com
      RELAY_TOKEN: ${RELAY_TOKEN}
      DB_HOST: db-prod.internal
      DB_PASSWORD: ${DB_PASSWORD}
    restart: unless-stopped

Troubleshooting

Symptom	Cause	Fix
Relay can’t connect to Concourse	Outbound HTTPS blocked	Verify the relay host can reach the Concourse URL over HTTPS. Check firewalls and proxies.
Database unreachable	Wrong host/port/credentials	Test connectivity from the relay host: psql -h <host> -p <port> -U <user> <database>.
Relay shows offline in Concourse	Token mismatch or network issue	Verify the relay token matches the one issued during registration. Check relay logs for connection errors.
Queries time out	Slow query or network latency	Check database performance. Consider adding query timeouts at the database level.