Starting Your Instance

spl serve is your Syncropel instance. It runs in the background, owns ~/.syncro/hub.db, binds an HTTP port for the API, binds a Unix socket (Linux and macOS) for the local CLI, and runs the four engine loops (ingest, reconcile, tick, cron).

There are three ways to start it. Pick by situation.

Dev mode — --insecure-localhost

spl serve --insecure-localhost

Use this the very first time, and any time you're doing local development without paired external devices.

What it does:

• Forces the bind address to 127.0.0.1 (loopback only — never reachable from another machine, regardless of --host).
• Sets auth.required = false for the lifetime of this instance.
• Logs a WARN line on startup so you notice if it's accidentally left on.

This mode is the escape hatch for the chicken-and-egg problem: if auth.required = true but no service account exists yet, the instance will refuse to start (fail-closed). --insecure-localhost lets the instance come up so you can create the first service account, save the token, then flip back to secure mode. Full flow on the next page.

Never run this on a host you didn't boot yourself. The guard against external reachability is strong, but the principle still holds: --insecure-localhost is for your laptop, not for anything shared.

Secure local mode — spl serve

spl serve

This is the default and what every long-running instance should use.

What it does:

• Binds 127.0.0.1:9100 (and the Unix socket at ~/.syncro/run/spl.sock on Linux and macOS).
• Enforces auth.required = true. Every request needs a valid bearer token.
• Refuses to start if no service account authorizes the operator's actor DID (the fail-closed guard referenced above).
• Takes a startup backup of hub.db to ~/.local/share/syncropel/backups/hub.db.bak (see Operator runbook for backup discipline).

The instance stays bound to loopback, which means nothing outside the machine can reach it. To expose it beyond loopback, see Exposing your instance securely.

Exposed mode — --host 0.0.0.0

spl serve --host 0.0.0.0

Binds to every interface on the machine. This is what you pass when the instance is meant to be reached from outside — typically from a phone on the same private network, a federation peer, or a reverse proxy.

Exposure is a separate decision from authentication. --host 0.0.0.0 without auth.required = true is a catastrophic misconfiguration. The default is to keep auth on. spl doctor flags instances bound to non-loopback with auth off.

Read Exposing the instance securely before using this flag. There are safer paths (Tailscale, reverse proxy) for almost every case where you might reach for 0.0.0.0.

Lifecycle

Check status

spl status

Reports version, PID, uptime, record count, store backend, and whether the instance responds on /health. No instance running prints Status: not running. If status says not running but a process is bound to the port anyway, see Troubleshooting → stale PID file.

Stop

spl stop

Sends SIGTERM to the instance, waits for graceful shutdown, flushes the WAL, closes the socket, removes the PID file. If the instance is unresponsive, the stop command falls back to SIGKILL after a grace period.

Restart

spl restart

Stop, then start, preserving the same arguments the instance was running with. Useful after a config file edit.

Tail logs

spl serve --logs

Streams the instance log. Equivalent to tail -f ~/.syncro/logs/spl.log but correctly locates the log file across platforms.

For targeted filtering, the JSON-line log format is easy to grep:

tail -f ~/.syncro/logs/spl.log | grep ERROR

Log locations

Logs rotate automatically at 10 MB per file, keeping the last 7 rotations.

What a successful start looks like

$ spl serve
Starting Syncropel instance...
Store:    sqlite:///home/you/.syncro/hub.db
Backup:   ~/.local/share/syncropel/backups/hub.db.bak (written)
Bind:     127.0.0.1:9100
Socket:   ~/.syncro/run/spl.sock
Auth:     required (service accounts: 1)
PID:      12847

Instance started. Run 'spl status' to verify health.

The instance comes up healthy with zero service accounts, and the local CLI talks to it via the Unix socket — see First run and Service accounts. The line Auth: required (service accounts: 0) is fine; the rich HTTP surface over TCP requires a bearer token until you pair a device or mint a service account.

See also

• Service accounts and tokens — delegation primitive (browser pair, paired phone, MCP, remote CLI)
• Keeping your instance running — make spl serve auto-start at login (systemd / launchd / Windows Service)
• Exposing your instance securely — go beyond loopback
• Operator runbook — day-2 lifecycle, upgrades, recovery
• spl doctor — fast triage when the instance is misbehaving