菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
| 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"] |
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.
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
synapse-api (Go), Postgres, Caddy, plus N
Convex backend containers.dev,
prod, or preview. Each has its own SQLite (or Postgres+S3 if HA),
admin key, and URL.<deployment-name>.app.<host>, e.g.
brave-dolphin-1060.app.synapsepanel.com). Optionally a per-deployment
custom domain (api.client.com).| 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 |
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).
synapse-deploysynapse-debugsynapse-envsynapse-multi-deploymentsynapse-cli-reference| 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 |
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.
基于 SOC 职业分类
Build and maintain the Synapse auto-installer (v0.6) — pure-bash setup.sh + supporting helpers + bats tests. Use when the user asks to "work on the installer", "improve setup.sh", "add a pre-flight check", "make installation easier", or anything under installer/ / setup.sh in the repo.
Run Aster's end-to-end docker smoke tests, including the v0.6 module-query smoke that proves a real `npx convex deploy` bundle executes inside a v8cell against real Postgres. Use when the user asks to "smoke aster", "test aster end-to-end", "prove aster works", "run aster docker smoke", or wants to verify the Aster integration after pulling new aster-runner changes.
Add a new feature end-to-end across Synapse — backend handler + integration test + dashboard UI + Playwright spec + API docs + commit. Use when the user asks to "add a new endpoint", "build a new feature", "expose X via the API", or any task that crosses backend + frontend boundaries.
Diagnose common Synapse failures — CORS errors in the browser, deployments stuck "provisioning", containers that can't reach each other inside the synapse-network, postgres connection refused, dashboard 401 loops, Playwright timing issues. Use when the user reports something in Synapse "isn't working", "is broken", "won't start", or shows error symptoms.
Spin up the Synapse local dev stack (postgres + Go backend), reset the database, run smoke tests against the API. Use when the user asks to "run synapse", "start the backend", "reset the db", "rebuild and run", or wants to manually exercise endpoints.
Exercise the Synapse API end-to-end with curl flows that cover the happy path plus the standard 401/403/404/409 negative cases. Use when the user asks to "test the API", "verify the backend", "run smoke tests", or after touching auth/teams/projects/deployments handlers.
