Cockpitify Docs Search the docs⌘K Product Sign in Try the live demo

Connect your own Postgres

Updated · Every plan · Phone · Web

Run the Cockpitify ops-runner next to any Postgres 15+ (your own server, RDS, Neon, Cloud SQL), or send the setup to whoever runs the server.

If your app’s database is a Postgres outside Supabase, you run one small container next to it: the ops-runner. It adds the same isolated ops layer to your database that Supabase projects get, and it talks to Cockpitify. Cockpitify never connects to your database, and your users’ data stays there.

Start in the app

  1. Connect → Your own Postgres.
  2. Name the app and say who sets up the server: I do, or Someone else.
  3. With I do, the app shows a pairing code and the command to run. With Someone else, it gives you a link to send; it opens a page with the code and the commands filled in.

The app shows up in your apps at once as Waiting for your server. The code works once, for 7 days. New code stops the old one and any link you sent.

Let an AI assistant set it up

Claude Code, Cursor, Codex and other coding agents can do the server part with the Cockpitify skill. On the server (or a machine that reaches it):

npx skills add cockpitify/cockpitify-skills

Then ask: “Connect our Postgres to Cockpitify with the ops-runner. The pairing code is YOURCODE.” The assistant checks the database, writes the container file, sets up HTTPS, starts the runner and confirms it paired. It never needs your Cockpitify login.

What the server needs

  • PostgreSQL 15 or newer, and a database user that can create schemas.
  • Docker (or Docker Compose).
  • An HTTPS address the internet can reach. The Cockpitify app, the web console and our backend call the runner there.

Run the container

docker run -d --name cockpitify-ops -p 8080:8080 --restart unless-stopped \
  -e DATABASE_URL='postgres://USER:PASSWORD@HOST:5432/DB' \
  -e OPS_HOST_KEY="$(openssl rand -hex 32)" \
  -e OPS_PUBLIC_URL=https://ops.example.com \
  -e OPS_PAIRING_CODE=YOURCODE \
  ghcr.io/cockpitify/ops-runner:0.82.0
Setting
DATABASE_URLThe database the ops layer goes into.
OPS_HOST_KEY32 characters or more. Encrypts the service keys you add later (OpenAI, RevenueCat…) in your database. Keep it: without it they can’t be read, and you’d enter them again.
OPS_PUBLIC_URLThe HTTPS address that reaches this container.
OPS_PAIRING_CODEThe code from the app. Only needed on the first start.

On its first start the runner installs the ops layer in one transaction (under a second) and pairs with the code. The app then ticks through Runner paired and First heartbeat, and you get a push.

Give it an HTTPS address

  • Your domain. Point a name like ops.yourapp.com at the server and put Caddy or nginx in front of port 8080. Caddy gets the certificate by itself.
  • Cloudflare Tunnel. No open port and no certificate to manage: a free tunnel container forwards your name to the runner.

After it connects

  • Your users table. On the web: Settings → People. Pick the table and columns that hold your users. Without it, Users stays empty.
  • How data reaches your server. In Usage tracking (app and web) the owner or an admin sets two things:
    • Your sign-in: the address of its public keys (JWKS) and its issuer. Signed-in devices send their sign-in token, and each event counts for the right person. Supabase Auth, Firebase, Clerk and Auth0 all publish one.
    • Server key: Make a key shows it once. Your own server sends it with usage events (/v1/ingest/server) and AI calls (/v1/usage). A new key stops the old one at once.
  • AI cost per user. On your server, @cockpitify/node sends each AI call to the runner with the server key: pass Ops.httpUsage({ url: 'https://ops.yourapp.com', key }) where a Supabase project would pass its client.
  • RevenueCat, Sentry and Expo webhooks go to the runner’s address: /webhooks/revenuecat, /webhooks/sentry, /webhooks/expo.

Update and remove

  • Update: run the new image. On start it brings the ops layer to its version; your data stays.
  • Remove: App settings → Remove in Cockpitify, then stop the container. The ops layer itself stays in your database until you drop the ops and cockpit schemas.

Not connecting?

The runner’s log says why: docker logs cockpitify-ops. The usual reasons are a wrong DATABASE_URL, an OPS_PUBLIC_URL that isn’t public HTTPS, or a code that was already used or replaced.

Was this page helpful?YesNo
Ask a question
Questions? Ask me.I’m Murat, the indie developer behind Cockpitify.

I read every message and reply by email, usually within a day.