Operate Joel's local self-hosted Convex setup with Central Postgres and NAS-backed Garage/S3-compatible object storage. Use when: 'local convex', 'self-hosted convex', 'Convex S3', 'Convex Garage', 'Garage', 'Convex MinIO', 'Convex buckets', 'run Convex locally', or any task wiring/debugging the local Convex runtime.
91%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Operate Joel's local self-hosted Convex setup. This is not generic Convex advice. It is the local joelclaw path: Central Postgres for database state and Garage on three-body for S3-compatible object storage. The custom MinIO install is now a rollback/reference path. ASUSTOR MinIO CE is only a temporary smoke-test reference.
Read these before mutating the setup:
/Users/joel/.brain/projects/convex-self-hosting-local.svx/Users/joel/Documents/Codex/2026-06-17/we-re-setting-up-durable-self/outputs/install-three-body-convex-garage.sh/Users/joel/Documents/Codex/2026-06-17/we-re-setting-up-durable-self/outputs/three-body-convex-minio-runbook.md/Users/joel/Documents/Codex/2026-06-17/we-re-setting-up-durable-self/outputs/install-three-body-convex-minio.shIf those disagree, prefer the brain project note for current truth, then verify live state with non-secret health checks.
three-body100.67.156.41three-body as a human label, not the Convex S3 endpoint.AS6508T5.1.3.RI81joelclaw service user:
/opt/homebrew/opt/postgresql@17/bin/postgres/Users/Shared/joelclaw/data/postgres/Users/Shared/joelclaw/etc/postgres/postgresql.conf127.0.0.1:5432/Users/Shared/joelclaw/run/.s.PGSQL.5432three-body.http://100.67.156.41:39100/volume1/joelclaw/s3/garage/data/volume1/joelclaw/s3/garage/meta/volume1/joelclaw/s3/garage/snapshots/volume1/joelclaw/s3/garage-compose/compose.yaml/volume1/joelclaw/s3/garage-compose/convex-s3.env/volume1/joelclaw/s3/garage-compose/convex-s3.redacted.envCustom MinIO is a rollback/reference path, not canonical:
http://100.67.156.41:39000http://100.67.156.41:39001/volume1/joelclaw/s3/minio/data/volume1/joelclaw/s3/minio-compose/compose.yaml/volume1/joelclaw/s3/minio-compose/convex-s3.envASUSTOR MinIO CE is not canonical:
http://100.67.156.41:29990http://100.67.156.41:29991/share/MinIOCE/dataminioadmin / minioadminPassWD9001Garage should have these Convex buckets:
joelclaw-local-usw2-convex-exportsjoelclaw-local-usw2-convex-snapshot-importsjoelclaw-local-usw2-convex-modulesjoelclaw-local-usw2-convex-filesjoelclaw-local-usw2-convex-searchUse the generated secret values from the NAS env file. Do not print them in chat.
AWS_REGION=usw2
S3_ENDPOINT_URL=http://100.67.156.41:39100
AWS_S3_FORCE_PATH_STYLE=true
AWS_ACCESS_KEY_ID=<from /volume1/joelclaw/s3/garage-compose/convex-s3.env>
AWS_SECRET_ACCESS_KEY=<from /volume1/joelclaw/s3/garage-compose/convex-s3.env>
S3_STORAGE_EXPORTS_BUCKET=joelclaw-local-usw2-convex-exports
S3_STORAGE_SNAPSHOT_IMPORTS_BUCKET=joelclaw-local-usw2-convex-snapshot-imports
S3_STORAGE_MODULES_BUCKET=joelclaw-local-usw2-convex-modules
S3_STORAGE_FILES_BUCKET=joelclaw-local-usw2-convex-files
S3_STORAGE_SEARCH_BUCKET=joelclaw-local-usw2-convex-searchPrefer checks that do not reveal secrets:
tailscale ping --timeout=5s --c 2 three-body
nc -vz -w 5 100.67.156.41 39100
curl -sS -m 5 -o /tmp/garage-root.out -w '%{http_code}\n' http://100.67.156.41:39100/Garage does not allow anonymous S3 access; a 403 AccessDenied response from / proves the API is reachable.
For MinIO rollback/reference only:
curl -fsS -m 5 http://100.67.156.41:39000/minio/health/ready
nc -vz -w 5 100.67.156.41 39000
nc -vz -w 5 100.67.156.41 39001For CE reference only:
curl -fsS -m 5 http://100.67.156.41:29990/minio/health/readythree-body has reset SSH handshakes after bursts of concurrent probes.kex_exchange_identification or Not allowed at this time; do not hammer SSH.joel@three-body can inspect system state.joel is in administrators, but Docker socket access is still denied because /var/run/docker.sock is root:root with mode 660.sudo or an ADM/admin path.admin@three-body or root@three-body repeatedly; earlier bad auth contributed to lockout symptoms.joelclaw service user over the local socket:sudo -u joelclaw psql -h /Users/Shared/joelclaw/run -p 5432 -d postgreshost.docker.internal:5432.POSTGRES_URL should omit the database name. Convex derives the database name from INSTANCE_NAME; INSTANCE_NAME=joelclaw-convex maps to database joelclaw_convex.DO_NOT_REQUIRE_SSL=1.The Garage installer has already completed successfully. Re-run it only to reconcile the service after intentional edits:
ssh -t joel@three-body 'sudo sh /volume1/joelclaw/s3/install-three-body-convex-garage.sh'The installer:
joelclaw-garage separately from custom MinIO and ASUSTOR MinIO CE,39100,/volume1/joelclaw/s3/garage/data,/volume1/joelclaw/s3/garage/meta,/volume1/joelclaw/s3/garage/snapshots,/volume1/joelclaw/s3/garage-compose/convex-s3.env,Do not expose Garage to the public internet. LAN/tailnet only.
The current projectless setup staged a local runner at:
/Users/joel/Documents/Codex/2026-06-17/we-re-setting-up-durable-self/work/local-convexImportant files:
prepare-env.sh imports /volume1/joelclaw/s3/garage-compose/convex-s3.env from the NAS and writes a local .env without printing secrets.prepare-env.sh preserves the existing CONVEX_POSTGRES_PASSWORD and INSTANCE_SECRET when switching S3 endpoints; do not rotate database credentials just to change object storage.bootstrap-postgres.sh creates/updates the convex Postgres role and joelclaw_convex database via sudo -u joelclaw.compose.yaml starts ghcr.io/get-convex/convex-backend and ghcr.io/get-convex/convex-dashboard.generate-admin-env.sh stores the generated self-hosted admin key in app-admin.env without printing it.run.sh performs the bootstrap, starts the backend/dashboard, and writes the admin env.smoke-self-hosted-convex.sh deploys joelclaw-api/convex, writes/reads/removes a temporary row, exports a snapshot, and verifies the export ZIP.Convex is intentionally exposed by named interfaces and ports only. Do not change this to a wildcard 0.0.0.0 bind.
Current verified URLs:
# Local
http://127.0.0.1:3210
http://127.0.0.1:3211
http://127.0.0.1:6791
# Tailnet (through the Origin proxy)
http://<host-tailnet-ip>:3210
http://<host-tailnet-ip>:3211
http://<host-tailnet-ip>:6791The LAN listener is retired (sec-20261103-003, 2026-11-03): the old
com.joelclaw.local-convex.lan-forwarder LaunchDaemon is booted out and
disabled. Do not bring it back; LAN clients use the tailnet address.
Implementation:
127.0.0.1 only.infra/central/native/convex-origin-proxy.mjs (tests: test-convex-origin-proxy.mjs)infra/central/native/install-convex-origin-proxy.sh (user LaunchAgents, no sudo; --uninstall points Serve back at Convex)127.0.0.1:13210 -> 3210 and 127.0.0.1:13211 -> 3211Origin (convex CLI, Node and bun clients) pass; browser requests pass only from the allowlist in ~/.config/joelclaw/convex-origin-proxy.json; foreign and null Origins get 403 on HTTP and WebSocket upgrades, logged to ~/.local/log/convex-origin-proxy.errx-convex-origin-proxy: 1com.joelclaw.convex-origin-proxy-check probes both ports every 300 s and sends one Rat King message per up/down change3210 -> 127.0.0.1:13210 (proxy)3211 -> 127.0.0.1:13211 (proxy)6791 -> 127.0.0.1:6792 (tailnet dashboard)NEXT_PUBLIC_DEPLOYMENT_URL to the tailnet Convex address (LAN_DASHBOARD_DEPLOYMENT_URL and TAILNET_DASHBOARD_DEPLOYMENT_URL in the compose .env); their Origins are on the proxy allowlist.Known Docker Desktop gotcha:
cannot assign requested address.Manage the proxy:
cd /Users/joel/Code/joelhooks/joelclaw
CONVEX_PROXY_ALARM_AS=<sender name> CONVEX_PROXY_ALARM_TO=<desk> ./infra/central/native/install-convex-origin-proxy.sh
launchctl print gui/$(id -u)/com.joelclaw.convex-origin-proxy
node --test infra/central/native/test-convex-origin-proxy.mjsManage tailnet forwards without disturbing unrelated Tailscale Serve config:
tailscale serve --bg --yes --tcp 3210 tcp://127.0.0.1:13210
tailscale serve --bg --yes --tcp 3211 tcp://127.0.0.1:13211
tailscale serve --bg --yes --tcp 6791 127.0.0.1:6792
tailscale serve status --json
# Disable only the Convex forwards if needed.
tailscale serve --tcp=3210 off
tailscale serve --tcp=3211 off
tailscale serve --tcp=6791 offDo not run tailscale serve reset casually; there may be unrelated Serve routes on this node.
Exposure checks:
curl -fsS -m 5 http://127.0.0.1:3210/version
curl -fsS -m 5 http://<host-tailnet-ip>:3210/version
curl -fsSI -m 5 http://127.0.0.1:13210/version | grep -i x-convex-origin-proxy # proxy answers
# A foreign Origin must get 403; no Origin must reach Convex.
curl -s -o /dev/null -w '%{http_code}\n' -X POST -H 'Origin: https://evil.example' \
-H 'content-type: application/json' -d '{"path":"x:y","args":{}}' http://<host-tailnet-ip>:3210/api/mutation
# The LAN address must refuse connections (listener retired).
curl -fsS -m 5 http://<host-lan-ip>:3210/version || echo "refused, as intended"
curl -fsSI -m 5 http://127.0.0.1:6791
curl -fsSI -m 5 http://<host-tailnet-ip>:6791
lsof -nP -iTCP:3210 -iTCP:3211 -iTCP:6791 -iTCP:6792 -iTCP:13210 -iTCP:13211 -sTCP:LISTENThe healthy self-hosted backend /version response is currently unknown.
.env, convex-s3.env, admin tokens, root credentials, access keys, or secret keys.three-body where the env file already lives.When asked to wire or debug local Convex:
39100.39100 counts for the current canonical path.0.0.0.0 just because Docker port binding is convenient. Use selected LAN/tailnet forwards.joelhooks/joelclaw
1fb2468
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.