| name | synapse-overview |
| description | Background on Synapse — the self-hosted Convex control plane this project uses instead of (or alongside) Convex Cloud. Loads when the agent needs context on what Synapse is, how it differs from Convex Cloud, or what the project's runtime architecture looks like.
|
| autoTrigger | ["when the user asks \"what is synapse\" / \"como funciona o synapse\"","when explaining differences vs Convex Cloud","when the agent needs runtime-architecture context (which container holds state, where deploys live, who owns the URL)","first time the agent reads this project — load this to ground all subsequent answers in the right model"] |
Synapse — context for AI agents working in this project
This project's Convex backend is hosted on Synapse, an open-source
self-hosted alternative to Convex Cloud. Anything that would have hit
*.convex.cloud in a Cloud setup goes through the Synapse host
instead.
Heads up to the agent: "Synapse" and "Convex" are not the same
thing. Synapse is the control plane (teams / projects / multi-deployment
management) — Convex itself (the database + query engine + functions
runtime) is unchanged. Each Synapse deployment runs the official
open-source Convex backend container.
Mental model
your laptop ────► npx convex (CLI) ────► one Convex backend container
│ (= a Synapse deployment)
│
└─► synapse CLI wraps ◄── the synapse-api Go service
and injects creds routes traffic to the right
from the host container by Host header
- Host: a VPS running
synapse-api (Go), Postgres, Caddy, plus N
Convex backend containers.
- Team: groups users + projects (synapse-side concept).
- Project: like Convex Cloud projects — has env vars, members, and
one or more deployments.
- Deployment: a single Convex backend container of type
dev,
prod, or preview. Each has its own SQLite (or Postgres+S3 if HA),
admin key, and URL.
- URL form: wildcard subdomain by default
(
<deployment-name>.app.<host>, e.g.
brave-dolphin-1060.app.synapsepanel.com). Optionally a per-deployment
custom domain (api.client.com).
Cloud vs Synapse — quick diff table
| Surface | Convex Cloud | Synapse |
|---|
| Auth | Account-based, ~/.convex/config.json | Per-host JWT, ~/.synapse/config.json |
| Local config | CONVEX_DEPLOYMENT=dev:<name> in .env.local | CONVEX_DEPLOYMENT commented, CONVEX_SELF_HOSTED_URL + CONVEX_SELF_HOSTED_ADMIN_KEY active |
| Dashboard | dashboard.convex.dev | operator's own host (e.g. synapsepanel.com) |
| API URL | <name>.convex.cloud | <name>.app.<host> |
| HTTP Actions URL | <name>.convex.site (separate domain) | same as API URL (one container, two routes) |
| CLI you run | npx convex … directly | synapse … which wraps npx convex with the right creds |
| Deployment provisioning | Cloud handles it | Each deployment is a Docker container on the host VPS |
Why this matters for code generation
When generating commands, scripts, or CI configs that touch the Convex
backend, prefer synapse over npx convex directly:
| Want to … | Right command | Wrong (will fail or hit wrong env) |
|---|
| Watch + push schema | synapse dev | npx convex dev (no creds) |
| Push to prod | synapse deploy | npx convex deploy (no creds) |
Run any other npx convex subcommand | synapse convex <args> | npx convex <args> direct |
| Get deployment credentials | synapse credentials <name> | manual lookup |
The synapse wrapper injects CONVEX_SELF_HOSTED_URL +
CONVEX_SELF_HOSTED_ADMIN_KEY into the child env so the underlying
Convex CLI authenticates correctly. It also strips
CONVEX_DEPLOYMENT from the env (the Convex CLI errors if both modes
are set together).
What to load next
- For deploy-shaped questions → load
synapse-deploy
- For "X is broken" / debugging → load
synapse-debug
- For env vars / secrets → load
synapse-env
- For dev vs prod vs preview workflows → load
synapse-multi-deployment
- For a full command catalog → load
synapse-cli-reference
Files this project carries (Synapse-related)
| Path | Purpose | Commit it? |
|---|
.synapse/project.json | links cwd to a team/project/deployment | Yes — shared by team |
.env.local | Convex credentials for THIS machine | No — gitignored (admin key) |
.synapse/skills/ | these AI agent skills | Yes — shared |
.claude/skills/synapse-* | symlinks → .synapse/skills/synapse-* | No — per-machine, gitignored |
~/.synapse/config.json | this machine's session JWT | No — outside repo |
Sanity check the agent can run
If you're not sure the project is properly linked, run
synapse doctor. It enumerates ~19 health checks (Node version, env
file, backend reachability, deployment health, optional local-HTTPS
dev category) and exits 0/1/2 based on severity. Includes auto-fix
flags (--fix --yes) for the recoverable ones.
