Self-host quickstart

This installs a Synap pod from a published release: pre-built container images pulled by digest, behind Caddy with automatic HTTPS. Nothing is built on your server. The Run section covers each step in depth.

What you needCopy Anchor Link

• A Linux server you can reach as root (sudo), with ports 80 and 443 open to the internet.

• A domain you control. The pod uses two host names, for example:

  • pod.example.com for the pod itself (API, sign-in, MCP),
  • pod-admin.example.com for the pod's admin console.

  Point a DNS A (or AAAA) record for both names at the server before you install, so the certificates can be issued.

• An email address for Let's Encrypt.

The installer installs Docker (from get.docker.com) if it is missing, and curl, tar, jq and openssl through apt-get if they are missing. On a distribution without apt-get, install those yourself first. Docker Compose v2 is required.

1. InstallCopy Anchor Link

curl -fsSL https://github.com/synap-core/backend/releases/download/channel-stable/install.sh \
  | sudo bash -s -- --domain pod.example.com --email you@example.com

What this does:

1. Resolves the latest stable release and downloads its release manifest (release.json).
2. Downloads that release's deploy bundle, checks it against the manifest's SHA-256, and unpacks it into /opt/synap.
3. Links the server CLI to /usr/local/bin/synap.
4. Runs synap install --non-interactive with your flags: writes /opt/synap/deploy/.env with generated secrets, pulls the images and starts the stack.

The admin console host name is derived from --domain: pod.example.com gives pod-admin.example.com.

2. Check the podCopy Anchor Link

The server CLI works on the deploy directory. Run it from there:

cd /opt/synap/deploy
sudo synap health
curl -fsS https://pod.example.com/health

If a certificate is not issued yet, check that both DNS records point at the server, then look at Caddy's logs with sudo synap logs caddy.

3. Create the first adminCopy Anchor Link

Mint a one-hour sign-up link for the first admin, and open it in your browser:

cd /opt/synap/deploy
sudo synap setup admin --email you@example.com --magic-link

The command prints a link to https://pod.example.com/setup?token=…. Open it and choose your password.

To create the admin directly instead, without a link:

sudo synap setup admin --email you@example.com --password '<a strong password>'

sudo synap setup admin --status prints needed while the pod has no admin, and ready once it has one.

4. Connect your laptop and agentsCopy Anchor Link

On your laptop (not on the server):

npx @synap-core/cli init --pod-url https://pod.example.com

It asks you to approve your laptop with a code (sign in to your pod in the browser to approve), connects the AI agents it finds (Claude Code, Codex, Cursor), and offers a pairing link for Relay on your phone. See the Cloud quickstart for each step; they are the same against your own pod.

5. Set up off-host backupsCopy Anchor Link

The pod dumps its databases every hour on the server, but a copy on the same disk does not survive losing the server. Configure an off-host repository and keep the recovery kit it prints: Backups.

NextCopy Anchor Link

• Configuration: change a setting with synap config.
• Upgrades: synap update, release channels and automatic updates.
• Operations: health, logs and troubleshooting.