Skip to main content
This walkthrough gets you from a fresh op-data account to a live Postgres connection with a working preview query. You will deploy the data-plane agent into your own environment, point it at a Postgres database, and confirm the round-trip by running a SELECT from the op-data UI.

​
Before you start

You will need:
  • An op-data workspace. Sign in at app.op-data.com and create or join an organization.
  • A host you control that can run a container and reach the public internet on outbound port 443. A developer laptop works for testing; any Linux VM, Kubernetes pod, or ECS task works for production.
  • A Postgres database the agent can reach, plus credentials with read access to the tables you want to preview.
No inbound network rules, VPC peering, or cloud-provider roles are required.

​
1. Provision an agent deployment

In the op-data UI, open Settings → Agent deployments and click Provision. op-data creates a dedicated WorkOS Connect M2M client for this deployment and returns three values:
  • OP_WORKOS_CLIENT_ID
  • OP_WORKOS_CLIENT_SECRET
  • OP_WORKOS_AUTHKIT_BASE_URL
Copy them — the client secret is shown once. You can rotate it later by clicking Revoke and reprovision on the same page.

​
2. Run the agent

The agent ships as a single Docker image. The minimum configuration is four environment variables plus a Postgres database URL for the agent’s own state: 
docker run --rm \
  -e OP_TENANT_ID=org_your_workspace_id \
  -e OP_CONVEX_URL=https://api.op-data.com \
  -e OP_WORKOS_AUTHKIT_BASE_URL=... \
  -e OP_WORKOS_CLIENT_ID=... \
  -e OP_WORKOS_CLIENT_SECRET=... \
  -e OP_AGENT_DATABASE_URL=postgres://user:pass@host:5432/agent \
  -p 8080:8080 \
  ghcr.io/op-data/agent:latest
You should see a log line like temporal-worker connected followed by http listening on :8080. curl http://localhost:8080/healthz should return ok. See Deploying the agent for the full reference — TLS for Temporal, canonical output URIs, AWS credentials for S3 sinks, etc.

​
3. Confirm the agent is registered

Back in the op-data UI, the Agent deployments page should now show your agent as Connected, with a recent heartbeat timestamp. If it stays on Pending for more than a minute, see Deploying the agent → Troubleshooting.

​
4. Add a Postgres connection

Open Connections → New connection, pick Postgres, and fill in host, port, database, username, password, and SSL mode. Click Test connection. The UI sends the credentials through a Temporal workflow that runs on your agent — the password never lands in op-data’s control plane. On success, you will see Connected and a validatedAt timestamp.

​
5. Run a preview query

From your new connection, click Preview query and enter a read-only statement: 
select id, email, created_at
from public.users
order by created_at desc
The agent executes the query against your database, caps the result at 100 rows, sanitizes values, and returns a small tabular payload for the UI to render. This is the one place op-data’s control plane receives row data — see Security for why this is safe by construction.

​
Next steps

  • Connecting Postgres — field-by-field reference, SSL modes, and least-privilege user setup.
  • Security — what op-data sees and what stays in your perimeter.
  • Architecture — how the control plane and data plane fit together.