Install

The supported install path is install.sh, published with every release of the backend. It bootstraps a bare host and hands over to the server CLI (synap install), which does the actual install. Images are pulled by digest from the release manifest; nothing is built on the host.

Install the stable releaseCopy 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

Arguments after -- go to the installer.

What install.sh doesCopy Anchor Link

1. Prerequisites. Installs curl, tar, jq and openssl with apt-get if one is missing (on a system without apt-get it stops and asks you to install it), installs Docker with get.docker.com if it is missing, and requires Docker Compose v2.
2. Release manifest. Downloads release.json for the release you asked for: stable by default.
3. Signature. Checks the manifest's keyless signature from Synap's CI with cosign, if cosign is installed. See Verifying releases.
4. Deploy bundle. Downloads the release's deploy bundle (the synap script, deploy/ and Kratos configuration), checks its SHA-256 against the manifest, and unpacks it into /opt/synap.
5. CLI on PATH. Links /opt/synap/synap to /usr/local/bin/synap.
6. Install. Runs synap install --non-interactive --release <id> in /opt/synap, with every other flag you passed.

Run again with the same release, it re-enters synap install, which is idempotent and keeps your existing deploy/.env. To move to another release, use synap update (see Upgrades).

install.sh optionsCopy Anchor Link

Environment variables: SYNAP_RELEASE (same as --release), SYNAP_DIR (same as --dir), SYNAP_BIN_DIR (default /usr/local/bin) and SYNAP_RELEASE_VERIFY (see below). SYNAP_DOMAIN, SYNAP_EMAIL, SYNAP_ADMIN_EMAIL and SYNAP_SMTP_URI are accepted as aliases of the matching flags.

synap install flagsCopy Anchor Link

These are passed through by install.sh. The installer always runs non-interactively.

Run synap install --help on the server for the complete list.

Retired flagsCopy Anchor Link

install.sh refuses the flags of the retired installer with their new spelling instead of ignoring them: --backend-version and --pod-agent-version (use --release), --control-plane-url and --provisioning-token (use --register-token with --control-plane), and --token (use --register-token). --with-openclaw is accepted and ignored: the pod no longer bundles an agent.

The first adminCopy Anchor Link

Unless you passed --admin-email and --admin-password, or registered the pod with --register-token (the person the code was created for becomes the owner), the pod starts with no admin. Create one from the server:

cd /opt/synap/deploy
sudo synap setup admin --email you@example.com --magic-link        # prints a one-hour sign-up link
sudo synap setup admin --email you@example.com --password '<secret>'   # or create the admin directly
sudo synap setup admin --status                                      # needed | ready

The link opens https://<your domain>/setup?token=…, where you choose a password. Once the pod has an owner, sudo synap setup admin --retire-token removes the bootstrap-only PROVISIONING_TOKEN from .env.

Verifying releasesCopy Anchor Link

Synap's CI signs every release manifest with a keyless cosign signature. SYNAP_RELEASE_VERIFY controls what the installer (and synap update) does with it:

Install cosign and set SYNAP_RELEASE_VERIFY=enforce to refuse unsigned or tampered releases. Set it on the sudo command, because sudo drops variables exported in your shell:

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

A manual synap update also reads SYNAP_RELEASE_VERIFY from deploy/.env.

Installing from a checkoutCopy Anchor Link

Developers can run ./synap install --from-source --domain localhost in a clone of the backend repository to build the images locally. This is a development path, not a way to run a production pod; see the contributing guide in the backend repository.