convex-synapse

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 27 Open GitHub ↗

Open-source control plane for self-hosted Convex deployments — the missing 'Big Brain' for multi-team, multi-project, multi-deployment Convex

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Synapse

[![Release](https://img.shields.io/github/v/release/Iann29/convex-synapse?label=release&color=blueviolet)](https://github.com/Iann29/convex-synapse/releases/latest)
[![CI](https://github.com/Iann29/convex-synapse/actions/workflows/ci.yml/badge.svg)](https://github.com/Iann29/convex-synapse/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://raw.githubusercontent.com/Iann29/convex-synapse/main/LICENSE)
[![Go](https://img.shields.io/badge/go-1.26%2B-00ADD8?logo=go)](https://go.dev/)
[![Next.js](https://img.shields.io/badge/next.js-16-000?logo=next.js)](https://nextjs.org/)

**The complete self-hosted [Convex](https://www.convex.dev/) platform.** Teams, projects, custom domains with auto-TLS, RBAC, S3 backups, audit trail, the official Convex Dashboard embedded with an in-iframe deployment picker. **One curl, three minutes, fully working.**

```bash
curl -sSf https://raw.githubusercontent.com/Iann29/convex-synapse/main/setup.sh | bash
```

The installer asks four questions (domain or HTTP, HA mode, install dir, auto-deps), then handles Docker, the stack, TLS, and a self-test end-to-end. You open `https://<your-domain>` (or `http://<vps-ip>:6790` for plain HTTP), register the admin, and the stack is yours.

> **Why this exists.** Convex's open-source backend ships solo — one deployment, one admin key, no concept of teams or projects. Convex Cloud has all that but it's closed and runs on someone else's machine. Synapse is the missing layer between "great single-instance backend" and "platform you control": you get the multi-deployment, RBAC, billing-account-shaped management surface that Cloud has, **without ever leaving your infra**.

**Already know what you want?** Skip the wizard and pass flags directly:

```bash
# Production with HTTPS
curl -sSf https://raw.githubusercontent.com/Iann29/convex-synapse/main/setup.sh \
  | bash -s -- --domain=synapse.yourdomain.com

# Local dev / no domain
curl -sSf https://raw.githubusercontent.com/Iann29/convex-synapse/main/setup.sh \
  | bash -s -- --no-tls --skip-dns-check --non-interactive
```

With a domain you get TLS via Caddy + Let's Encrypt automatically; without one, Synapse exposes plain HTTP on `:6790` (dashboard) and `:8080` (API). Validated end-to-end against a real Hetzner CPX22.

![Project page with a deployment provisioned](https://raw.githubusercontent.com/Iann29/convex-synapse/main/docs/screenshots/04-project-deployment.png)

## Multi-host (v1.18+, dashboard-driven since v1.19)

Run deployments across multiple VPSes from one Synapse control plane.
One-liner adds a new VPS as a "host"; place deployments via the
dashboard dropdown.

```bash
# On the Synapse control plane (one-time, v1.19+):
#   Admin → Remote Hosts → Configure (in the dashboard).
# CLI-equivalent for automation:
setup.sh --configure-headscale

# Dashboard → Hosts → New host → "Setup remote install"
# Copy the one-liner shown, SSH into the new VPS, paste:
curl -fsSL https://synapse.example.com/install-agent.sh \
  | sudo bash -s -- \
    --control-url=https://synapse.example.com \
    --headscale-auth=tskey-auth-... \
    --adoption-token=syn_adopt_...

# Refresh dashboard — host appears online in ~60s.
# Create a deployment with "Place on host" → vps-eu-1.
# Synapse central provisions the Convex container there via SSH.
```

Architecture: Headscale (self-hosted Tailscale control plane) +
per-host ed25519 SSH keys encrypted at rest + forced-command Docker
whitelist on the remote sshd. Zero third-party dependency on the
identity path. Full guide: [`docs/REMOTE_HOSTS.md`](docs/REMOTE_HOSTS.md);
security model + rotation: [`docs/SECURITY_REMOTE_HOSTS.md`](docs/SECURITY_REMOTE_HOSTS.md).

## What you can do with this

**Run a personal Convex backend, properly.** Sign up, create a team, spin up dev / preview / prod deployments, point your `npx convex` at them, watch the embedded official Convex Dashboard reflect every function call, every row, every log line — same UI Convex Cloud ships, on infrastructure you own.

**Replace your Cloud account without losing functionality.** Custom domains with on-demand TLS, scoped access tokens, deploy keys for CI integrations, project-level RBAC, audit log with Cloud-vocabulary action names, OpenAPI parity with the upstream dashboard's management API. The `npx convex` CLI talks to Synapse with the same shape it talks to Cloud. Migrate without rewriting client code.

**Upgrade from your phone.** A yellow "v1.X.Y available" banner in the dashboard polls GitHub releases hourly; one click triggers `setup.sh --upgrade` via a host-side systemd daemon (unix socket, no TCP exposure), streams logs back to the modal, and the page reloads when the new build is healthy. No SSH for routine upgrades.

## Architecture

```
                  🌐 Operator's browser / npx convex
                              │ HTTPS
                              ▼
            ┌───────────────────────────────────────────┐
            │  Caddy reverse proxy                      │
            │  • Let's Encrypt for <domain>             │
            │  • on-demand TLS for *.<base-domain>      │
            │  • /v1/internal/tls_ask gates issuance    │
            └───────────────────┬───────────────────────┘
                                │
┌───────────────────────────────▼───────────────────────────────┐
│  Synapse Dashboard            Next.js • teams · projects ·    │
│                               RBAC · audit · access-tokens    │
│                               port 6790                       │
│                               • /embed/<name> shell with      │
│                                 in-iframe deployment picker   │
└──────────────┬────────────────────────────────────────────────┘
               │ REST API (OpenAPI v1 compatible)
┌──────────────▼────────────────────────────────────────────────┐
│  Synapse API                  Go • chi • pgx • docker SDK     │
│                               port 8080                       │
│                               • Postgres (metadata)           │
│                               • /d/{name}/* reverse proxy     │
│                               • <name>.<base-domain> Host     │
│                                 routing for custom domains    │
└──────────────┬────────────────────────────────────────────────┘
               │ docker run
       ┌───────┼───────┐
       ▼       ▼       ▼
   ┌───────────────────────┐    ┌───────────────────────┐
   │ Convex backend × N    │    │ Convex Dashboard      │
   │ (one container per    │    │ (data / functions /   │
   │  deployment, ~1s spin │    │  logs UI, embedded    │
   │  up; 2× replicas in   │    │  under /embed/<name>) │
   │  HA mode)             │    │                       │
   └───────────────────────┘    └───────────────────────┘
```

## What works

| Feature | Notes |
|---|---|
| Auth | email + password, JWT for the dashboard, opaque PATs for CLI / CI |
| Teams + invites | multi-user via opaque tokens, admin / member roles |
| Projects | CRUD, rename, delete, transfer between teams, slug change, default env vars (batch) |
| Project-level RBAC (v1.0+) | admin / member / viewer overrides on top of team roles — lock a contractor to read-only on one project without touching the team |
| Deployments | one Convex backend container per deployment, ~1 s provisioning |
| Custom domains (v1.0+) | `SYNAPSE_BASE_DOMAIN=<host>` → deployment URLs become `https://<name>.<host>` with Caddy on-demand TLS |
| In-iframe deployment picker (v1.0+) | green-pill switcher above the embedded Convex Dashboard, one click to swap between dev / prod / preview |
| Adopt existing | register an external Convex backend without spinning a new one |
| `npx convex` CLI | signed admin keys + `cli_credentials` panel, paste-and-go |
| Reverse proxy | `/d/{name}/*` routing with multi-replica failover for HA |
| Convex Dashboard | hosted alongside Synapse, auto-logged via postMessage handshake |
| HA-per-deployment | opt-in: 2 replicas + external Postgres + S3, AES-GCM encrypted creds |
| Scoped access tokens (v1.0+) | user / team / project / app / deployment scope; bearer enforced at every load*ForRequest |
| Deploy keys (v1.0.3+) | named per-deployment admin keys for CI integrations (Vercel, GitHub Actions, etc) — create from the deployment row, revoke from the dashboard, audit trail per credential |
| Auto-update from the dashboard (v1.1.0+) | yellow "v1.X.Y available" banner polls GitHub releases hourly; one-click upgrade dispatches `setup.sh --upgrade` via a host-side systemd daemon (unix socket, no TCP exposure), streaming logs back to the modal — no SSH needed for routine upgrades |
| **Multi-host deployment (v1.18+, dashboard-driven since v1.19)** | One-liner agent install brings a VPS into the Synapse fleet; place deployments per-host via dashboard or `synapse deployment create --host=<id>`. SSH-based dispatch over Headscale tailnet (tag-based ACL default in v1.19+), per-host ed25519 keys encrypted at rest. v1.19+ surfaces enable/configure under **Admin → Remote Hosts** and routes `<deployment>.<base-domain>` for remote deployments through the central proxy automatically — no laptop tailnet join required. Full guide: [`docs/REMOTE_HOSTS.md`](docs/REMOTE_HOSTS.md). |
| Audit log | Cloud-vocabulary action names, admin-only read |
| Multi-node hygiene | retry-on-conflict, advisory-lock workers, `SELECT FOR UPDATE SKIP LOCKED` queue |
| Auto-installer | `./setup.sh` or `curl \| bash` one-liner brings up the whole stack on a fresh VPS in ~3 min |
| Interactive installer wizard (v1.0+) | zero-flag `curl \| bash` triggers a Q&A walkthrough (domain, HA, install dir) with auto-Docker-install — no docs needed |
| Lifecycle commands | `--upgrade` (auto-detect via GitHub Releases, snapshot rollback), `--backup` / `--restore` (with optional S3), `--uninstall`, `--logs`, `--status` |
| First-run wizard | dashboard `/login` → `/setup` on a fresh install: admin → demo team/project/deployment in three clicks |
| Pagination | `?limit&?cursor` + `X-Next-Cursor` on every list endpoint |
| OpenAPI parity | 100% of self-hosted-relevant subset; ~60 cloud-only paths return structured `404 not_supported_in_self_hosted` |
| API stability | semver on the `/v1/...` surface; deprecation policy + change log in [`docs/API.md`](docs/API.md) |

**Tests:** current checkout has 638 Go test functions + 123 Playwright e2e
tests + 513 bats unit cases, all expected green in CI on every push.

## Releases

Latest release:
[`github.com/Iann29/convex-synapse/releases/latest`](https://github.com/Iann29/convex-synapse/releases/latest).
This checkout's installer version is `1.19.0` (`setup.sh --version`).

`./setup.sh --upgrade` queries
[`/releases/latest`](https://github.com/Iann29/convex-synapse/releases/latest)
to discover the target tag automatically and falls back via snapshot
on failure. Versioning + deprecation policy lives in
[`docs/API.md`](docs/API.md) — semver on the `/v1/...` surface,
breaking changes bump major, error codes are stable, deprecations
get one minor cycle of dual-shipping before removal.

For roadmap, design notes, and what's deliberately out of scope, see
[`docs/ROADMAP.md`](docs/ROADMAP.md) and
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). For more screenshots,
see [`docs/SCREENSHOTS.md`](docs/SCREENSHOTS.md). The full docs index is
[`docs/README.md`](docs/README.md).

The **Cell Control Plane** (hosts, agents, cells, desired/observed/**drift** +
dry-run — observe & plan only, never applies) is documented under
[`docs/CELL_CONTROL_PLANE.md`](docs/CELL_CONTROL_PLANE.md).

## Quickstart

### Production VPS — with TLS (one-liner)

```bash
curl -sSf https://raw.githubusercontent.com/Iann29/convex-synapse/main/setup.sh \
  | bash -s -- --domain=synapse.yourdomain.com
```

DNS A-record must already point at the VPS. Caddy handles TLS via
Let's Encrypt automatically. The script clones the repo into
`/tmp/convex-synapse-bootstrap-<pid>` and re-execs itself from there
— operators see "Bootstrapping Synapse installer from ..." on stderr
before the real install starts.

### Local dev — no TLS, no domain

```bash
curl -sSf https://raw.githubusercontent.com/Iann29/convex-synapse/main/setup.sh \
  | bash -s -- --no-tls --skip-dns-check --non-interactive
```

Open `http://localhost:6790`, register, click around. Useful flags
worth knowing: `--enable-ha`, `--doctor`, `--install-dir=`,
`--upgrade [--ref=<tag>]`, `--backup [--to-s3=...]` /
`--restore=<archive|s3://...>`, `--base-domain=<host>` (for
wildcard custom-domain mode), `--no-bootstrap` (run from a local
checkout).

### Manual install (inspect first)

If you'd rather review the script before running it (good practice
for serious deploys), `git clone` and run it locally — same script,
same flags:

```bash
git clone https://github.com/Iann29/convex-synapse.git
cd convex-synapse && ./setup.sh --domain=synapse.yourdomain.com
```

For everything else (custom Caddy/nginx, HA cluster setup, the
`npx convex` flow), see
[`docs/PRODUCTION.md`](docs/PRODUCTION.md) /
[`docs/QUICKSTART.md`](docs/QUICKSTART.md) /
[`docs/HA_TESTING.md`](docs/HA_TESTING.md).

## Repo layout

| Path | Purpose |
|---|---|
| `synapse/` | Go control plane — REST API + provisioner + reverse proxy |
| `dashboard/` | Next.js dashboard talking to the REST surface |
| `setup.sh` + `installer/` | Pure-bash auto-installer + bats tests |
| `docs/` | Architecture, roadmap, production guide, design notes |
| `docker-compose.yml` | Local stack + optional `ha` / `caddy` profiles |

## Tests

```bash
# Go integration (postgres on :5432 or set SYNAPSE_TEST_DB_URL)
cd synapse && go test ./... -count=1

# Playwright e2e against the live compose stack
cd dashboard && npm ci && npx playwright install chromium && npm run test:e2e

# Bats — installer + setup.sh
docker run --rm -v "$PWD:/code" -w /code synapse-bats -r installer/test/
```

CI runs all four (Go, Next.js, compose build, Playwright) plus the
installer suite on every push.

## License

Apache License 2.0 — see [LICENSE](LICENSE).

The dashboard component is an original Next.js app talking to
Synapse's REST surface, not a fork of any Convex code. Reading the
Convex Cloud dashboard
[OpenAPI spec](https://github.com/get-convex/convex-backend/blob/main/npm-packages/dashboard/dashboard-management-openapi.json)
to design a compatible API is fair use; we ship no code from that
repo.

---

> Why "Synapse"? A synapse is the connection between neurons. Big
> Brain is the closed-source neuron Convex Cloud uses; Synapse is what
> wires self-hosted deployments together into something coherent.
> Also, it's short.

convex-synapse

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README