[alycda]

Why

Ghost does not replace Convex, and the reverse is also true. Ghost hands out disposable Postgres databases, so it is the test database. Convex is an app backend: server functions, auth, and live queries that push to subscribers. It is what create-epoch-app is built on. This PR runs the open-source backend and dashboard on venari, like Soft Serve and Ghost:

• a /srv/<name>/ twin in this repo
• loopback-only ports
• ssh -L from the laptop

It stores its data in Ghost's Postgres cluster, so the box runs one Postgres, not two.

What

• tools/venari/convex/: docker-compose.yml (twin of /srv/convex/), .env.example (role password), .gitignore
• tools/venari/ghost/docker-compose.yml: postgres also joins venari-postgres, which this project creates (fixed name:)
• tools/venari/README.md:
  • table row
  • a Convex section: isolation, network, TLS, split state, measurements, access, admin keys, the loopback-only limit, setup, upgrades
  • the backups gap and the Ghost section now name Convex's data and agree on what a box snapshot does and does not give
  • Ghost's backup note and the box's backup gap now name Convex's data
• tools/just/personal.just: convex-tunnel / convex-tunnel-close (an ssh control socket, so they work on macOS and Linux) and convex-admin-key (fails instead of printing a non-key)
• CLAUDE.md: venari's service list in the structure tree

No Nix changes and no agenix secret.

Decisions to review

• Isolation inside the shared cluster. Convex has its own database, convex_self_hosted, and its own role, convex. CONNECT is revoked from PUBLIC, so tsdbadmin, the shared role Ghost gives agents, cannot open the database. ghost-server only acts on databases in its own ghost.databases table (checked in the fork's internal/server/store.go), so it cannot list, size or drop Convex's database.
• One network, owned by Ghost. Ghost's compose creates venari-postgres; Convex's declares it external. Ghost runs with or without Convex. docker compose down in /srv/ghost while Convex is attached keeps the network ("Resource is still in use", exit 0), and Convex keeps running.
• A connection budget. The cluster allows 25 connections (3 for superusers). Convex's pool is capped at 8 (POSTGRES_MAX_CONNECTIONS, default 128), and its role has CONNECTION LIMIT 10, leaving about 12 for agents. Convex used 7 under a 500-mutation burst.
• Plaintext between the two containers. The backend verifies Postgres TLS, and Ghost's certificate is self-signed, so the handshake fails with CaUsedAsEndEntity. The fix takes both DO_NOT_REQUIRE_SSL=1 and ?sslmode=disable; either alone still fails. The hop never leaves the host. The alternative, not tested, is to re-issue Ghost's certificate from a CA the backend trusts.
• State is split between the database in the cluster and data/ (files, modules, credentials). A whole-disk box snapshot takes both at once (crash-consistent, if the provider snapshots atomically, which is unchecked). npx convex export is consistent by construction and is the only copy that leaves the box. Copying the two halves separately is not consistent.
• Pinned images. Both are on 0cf49cb, the revision :latest pointed at on 2026-09-22, pulled from ghcr.io/convex/. The old ghcr.io/get-convex/ path stopped working when the org was renamed: it answers denied even for :latest. Upstream's own compose file still names the old path.
• No outbound calls: DISABLE_BEACON and NEXT_PUBLIC_LOAD_MONACO_INTERNALLY are set.
• One user, on offset ports. The API origin is http://127.0.0.1:13210, the laptop's end of the tunnel (box port + 10000, like Ghost's 15432), because 3210/3211 are where a local npx convex dev deployment starts. This serves one person over ssh. A frontend other people use needs a second firewall port and a TLS proxy. That is a separate decision.

The first commit used SQLite. The second moves to the shared cluster, at the author's call.

Verification

In a sandbox, not on venari, with ghost-server built from the fork and Ghost set up per its README:

• A project deployed with a schema, a mutation, a query and a "use node" action (convex 1.46.0). A subscription saw 271 pushed updates across 500 concurrent mutations.
• tsdbadmin is refused on convex_self_hosted. ghost create, fork, delete and list are unaffected.
• Outages. With Ghost brought down and back up, Convex never restarted and kept its data. On a cold start with Convex first, it crash-looped 7 times, then recovered by itself.
• Peak memory. Backend 132 MiB and dashboard 88 MiB, against limits of 512m and 384m. ghost-postgres peaked at 213 MiB of 768m. The box's container limits total about 2 GB of 4 GB.
• Setup. The README's Convex setup block ran verbatim, starting from Ghost on its current compose file (no shared network), and ended in Connected to Postgres.

Since the code review (10 findings, one commit each): the tunnel, admin key and deploy were run through a real ssh -L to a stand-in sshd on Linux. Storage URLs come back on 13210 and serve through the tunnel. The tunnel recipes handle open, re-open, close, a stale socket and a bind conflict. The README setup ran verbatim again with the final files.

On venari (2026-10-16)

The README setup ran on the box, starting from Ghost on main's compose file. It found one bug: the images had moved to ghcr.io/convex/ (510d04f). After that fix:

• Setup. Ghost came back up with ghost-postgres re-created onto venari-postgres, so Ghost was down for a few seconds. The role and database were created, and the backend logged Connected to Postgres database: convex-self-hosted.
• Isolation. tsdbadmin is refused on convex_self_hosted ("User does not have CONNECT privilege"). From the laptop, ghost list shows Ghost's 2 databases and not Convex's.
• Connections. Convex holds 5 client connections against its role limit of 10 and the cluster's 25. TimescaleDB starts one background-worker scheduler per database, Convex's included, so Convex also takes a worker slot: 5 of 16 are in use.
• Ports. 3210, 3211 and 6791 listen only on the box's loopback.
• Recipes on macOS.
  • convex-tunnel opens, a second call reports "already open", and convex-tunnel-close closes it.
  • All three forwards bind to 127.0.0.1 only.
  • convex-admin-key returns a convex-self-hosted|<hex> key.
  • The dashboard on 16791 returns 200.
• Workload. A throwaway project (convex 1.46.0) with a schema, a mutation and a query deployed through the tunnel. The mutation and query worked (3 inserts, count 3), and the count was still 3 after docker compose restart backend.
• Idle memory. Backend 16 MiB, dashboard 91 MiB, ghost-postgres 67 MiB.

Not verified:

• load on venari's 2 vCPUs
• the dashboard in a browser with an admin key
• a reboot of the box (restart: unless-stopped across compose projects)

The smoke-test functions and their pings table (3 rows) are still deployed on venari.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Tw8tuRUyKtkcjmN4upeawF

---

Generated by Claude Code

[github-actions]

⊕ Entity-level changes

CLAUDE.md

Status	Type	Name
Δ	heading	Repository Structure

tools/just/personal.just

Status	Type	Name
Δ	chunk	lines 21-40
-	chunk	lines 41-48
+	chunk	lines 41-60
+	chunk	lines 61-80
+	chunk	lines 81-100
+	chunk	lines 101-101

tools/venari/README.md

Status	Type	Name
Δ	heading	venari — the always-on box
Δ	heading	Ghost: disposable Postgres for agents
+	heading	Convex: a self-hosted app backend
Δ	heading	Not covered yet

tools/venari/convex/.env.example

Status	Type	Name
+	chunk	lines 1-4

tools/venari/convex/.gitignore

Status	Type	Name
+	chunk	lines 1-2

tools/venari/convex/docker-compose.yml

Status	Type	Name
+	chunk	(preamble)
+	property	name
+	section	services
+	section	networks

tools/venari/ghost/docker-compose.yml

Status	Type	Name
Δ	section	services
+	section	networks

Summary: 12 added, 6 modified, 1 deleted across 7 files

_{functions and classes, not lines · sem}