Run your own SyncStaff server

One command takes a Debian or Ubuntu box—or any machine with Docker—to a private SyncStaff server with PostgreSQL and the dashboard included.

  1. 1. Install SyncStaff

    Run this on the server. The default installation binds only to loopback, generates its own database password, starts the containers, and waits for the API health check before reporting success.

    Data boundary before you install

    Repository source, local search indexes, embeddings, and repository credentials stay on each agent machine. The server stores coordination metadata in PostgreSQL: people and project identifiers, file paths, intents, leases, tasks, decisions, audit events, and interface-change summaries. Optional model arbitration is off unless you provide a model API key; when enabled, relevant coordination records are sent to that configured provider. Agent credentials are project-scoped and saved locally with owner-only permissions. See the security and trust page for procurement details.

    SyncStaff is running.

  dashboard   http://localhost:3000
  server URL  http://localhost:7377
  2. 2. Connect a repository

    On the computer where your agents work, run the command printed by the installer from inside the repository:

    npx -y syncstaff-mcp setup --server http://localhost:7377

    Setup asks for the project and agent client, writes the local integration, and verifies that an agent actually connects.

Let teammates reach the server over HTTPS

Point a hostname at the server and create a GitHub OAuth app whose callback is https://sync.example.com/auth/github/callback. Then run the installer with these environment variables:

sudo SYNCSTAFF_DOMAIN=sync.example.com SYNCSTAFF_GITHUB_CLIENT_ID=... SYNCSTAFF_GITHUB_CLIENT_SECRET=... sh -c 'curl -fsSL https://syncstaff.ai/install.sh | sh'

The domain path enables Caddy and automatic TLS. It refuses to publish the server unless OAuth is configured; an unauthenticated coordination API must never be exposed to the internet.

Optional LLM arbitration

Pass ANTHROPIC_API_KEY when first installing to enable model-assisted conflict arbitration. Without it, deterministic intents, leases, board policy, and blast-radius checks still work.

Updating

Re-run the same install command to keep the generated secrets and refresh the bundle. Pin a release with SYNCSTAFF_VERSION=v1.2.3.

Backups

The durable state is the Docker volume syncstaff-db. Back it up with pg_dump and verify recovery by restoring it to a separate volume.

Uninstalling

Stop the stack from /opt/syncstaff. Omitting -v preserves the database volume.

cd /opt/syncstaff && sudo docker compose down
Troubleshooting
  • The stack does not become healthy. Run cd /opt/syncstaff && docker compose logs api.
  • The setup command cannot reach a remote server. Use the HTTPS hostname printed by the domain-enabled install, not localhost.
  • Docker Compose is missing. Install Docker with the Compose v2 plugin, then re-run the installer.

Not sure you need to self-host? See how Syncstaff works first.