Installing SyncSSH

1. Clone and configure

$ git clone https://github.com/syncssh/syncssh.git
$ cd syncssh
$ cp .env.example .env
# Edit .env: set any non-empty SECRET_KEY for dev
$ docker compose up -d

2. Create your first local account

$ docker compose logs backend

$ docker compose exec backend python manage.py createsuperuser

$ docker compose exec backend python manage.py shell -c "
from django.contrib.auth import get_user_model
from organizations.models import Organization, OrganizationMembership, Role
user = get_user_model().objects.get(username='admin')
org, _ = Organization.objects.get_or_create(
    slug='local', defaults={'name': 'Local workspace'}
)
OrganizationMembership.objects.get_or_create(
    user=user, organization=org, defaults={'role': Role.OWNER}
)
print(f'{user.username} is an OWNER of {org.name}')
"

3. Try it

1. 1. Add a server in the dashboard. Copy the install command shown — it will look like:
   curl -sL http://localhost:8000/install/<token>/ | bash
2. 2. SSH into the bundled sandbox:
   ssh root@localhost -p 2222 — password is whatever you set as VPS_ROOT_PASSWORD (default: syncssh)
3. 3.
   Inside the testvps container, replace localhost with backend in the curl URL (docker DNS resolves backend to the backend container), then run it:

   $ curl -sL http://backend:8000/install/<token>/ | bash

   copy
4. 4. Back in the dashboard, add your SSH public key. Wait ~60 seconds.
5. 5. On the sandbox: cat ~/.ssh/authorized_keys — your key appears inside the # === SYNCSSH BEGIN === block.

Option 1 — Cloudflared tunnel recommended

# Install once
$ brew install cloudflared   # macOS
# or download from github.com/cloudflare/cloudflared/releases

# Start the tunnel while docker compose is running
$ cloudflared tunnel --url http://localhost:8000
  → https://random-words-1234.trycloudflare.com

Then edit .env with the printed hostname:

APP_BASE_URL=https://random-words-1234.trycloudflare.com
VITE_INSTALL_BASE_URL=https://random-words-1234.trycloudflare.com
ALLOWED_HOSTS=localhost,127.0.0.1,random-words-1234.trycloudflare.com

$ docker compose restart backend

The install URL in the dashboard now points at the tunnel. The VPS can curl it, and the cron worker can keep pulling over the tunnel indefinitely. Note: the free Cloudflared tunnel hostname changes on restart — fine for debugging, not for anything persistent.

Option 2 — ngrok

$ ngrok http 8000
  → https://abc123.ngrok-free.app

Set APP_BASE_URL and VITE_INSTALL_BASE_URL to the printed URL, same as Cloudflared above.

Option 3 — Tailscale

Put your laptop and the VPS on the same tailnet, then use your laptop's Tailscale IP or MagicDNS hostname:

APP_BASE_URL=http://your-laptop.tail12345.ts.net:8000
VITE_INSTALL_BASE_URL=http://your-laptop.tail12345.ts.net:8000
ALLOWED_HOSTS=localhost,127.0.0.1,your-laptop.tail12345.ts.net

Best option for ongoing dev against persistent VPSes — stable hostname, no public exposure, no tunnel to keep alive.

.env

DEBUG=False
SECRET_KEY=...  # openssl rand -base64 64
ALLOWED_HOSTS=ssh.yourco.com

APP_BASE_URL=https://ssh.yourco.com
VITE_INSTALL_BASE_URL=https://ssh.yourco.com
CORS_ORIGINS=https://ssh.yourco.com

DB_HOST=postgres.internal
DB_NAME=syncssh
DB_USER=syncssh
DB_PASSWORD=...

# SMTP for invite emails
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.sendgrid.net
EMAIL_HOST_USER=apikey
EMAIL_HOST_PASSWORD=...
EMAIL_PORT=587
EMAIL_USE_TLS=True
DEFAULT_FROM_EMAIL=noreply@yourco.com

Reverse proxy — Caddy simplest TLS

ssh.yourco.com {
    handle /assets/* {
        root * /var/www/syncssh/frontend/dist
        file_server
    }
    handle /api/*      { reverse_proxy 127.0.0.1:8000 }
    handle /install/*  { reverse_proxy 127.0.0.1:8000 }
    handle /accounts/* { reverse_proxy 127.0.0.1:8000 }
    handle {
        root * /var/www/syncssh/frontend/dist
        try_files {path} /index.html
        file_server
    }
}

For nginx: set proxy_set_header X-Forwarded-Proto $scheme; explicitly — syncssh trusts that header to recognise HTTPS-terminated requests.

Production checklist

• ✓ DEBUG=False — the app refuses to boot without a strong SECRET_KEY when debug is off.
• ✓ HTTPS via reverse proxy. Plain HTTP exposes bearer tokens in transit.
• ✓ Postgres with backups configured.
• ✓ Redis-backed cache for rate limits. The default in-memory cache is per-worker and per-process — per-IP throttles weaken on every restart or scale-out.
• ✓ APP_BASE_URL matches the public URL exactly (no trailing slash).
• ✓ SMTP configured for invite emails — invites silently queue in the console backend if not set.

When DEBUG=False, syncssh automatically enforces SESSION_COOKIE_SECURE, CSRF_COOKIE_SECURE, SECURE_SSL_REDIRECT, HSTS with subdomains and preload, X_FRAME_OPTIONS=DENY, and SECURE_CONTENT_TYPE_NOSNIFF. You don't configure any of these — they're locked on automatically.

Agent installed but nothing syncs

# On the target server
$ crontab -l
# Should show: * * * * * $HOME/.syncssh/sync-ssh.sh

# Run the worker manually with verbose output
$ bash -x ~/.syncssh/sync-ssh.sh

Backend logs show nothing useful

$ docker compose logs -f backend

A bare "Bad Request (400)" with no detail almost always means ALLOWED_HOSTS. Briefly set DEBUG=True, reproduce the error, fix the offending Host header, then set DEBUG=False again.

Frontend shows "Network Error" on every API call

$ curl -i http://localhost:5173/api/v1/auth/csrf/

• 200 → proxy is fine; check CORS_ORIGINS covers your dashboard origin.
• 502 → backend is down; run docker compose ps and docker compose logs backend.
• 404 → VITE_API_PROXY points at the wrong target.