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.

To be precise about what this flag is: it turns authentication off for a loopback-only instance. It has nothing to do with TLS or certificates — local instances speak plain HTTP on loopback either way.

You rarely need it: a fresh secure instance starts fine with zero service accounts (see bootstrap mode below), and the local CLI works over the Unix socket immediately. Reach for --insecure-localhost when you want the HTTP surface open without tokens — quick local scripts, curl exploration, throwaway dev instances.

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 HTTP request needs a valid bearer token.
• With zero service accounts, starts in bootstrap mode: the local socket works normally, and the TCP API answers 503 BOOTSTRAP_REQUIRED (with the exact commands to run) until you mint the first service account. The instance never refuses to start over missing accounts.
• Takes a startup backup of hub.db to ~/.local/share/syncropel/backups/instance-<did-tail>/hub.db.bak — a per-instance directory keyed by the instance DID (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

Start

spl start          # background (alias for `spl serve --daemon`)
spl serve          # foreground — canonical for systemd / Docker / supervisors

spl start is the convenience verb spl init recommends for interactive use; it supports the same flags as spl serve (--port, --memory, --echo, --store, --insecure-localhost).

A different port

spl serve --port 9200

--port (default 9100) is how a second instance shares a machine — each instance needs its own home directory too; see Running multiple local instances.

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/instance-<did-tail>/hub.db.bak (written)
Bind:     127.0.0.1:9100
Socket:   ~/.syncro/run/spl.sock
Auth:     required (service accounts: 0)
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 — Auth: required (service accounts: 0) is bootstrap mode, not an error. Until you mint the first service account, the TCP API answers every request with 503 BOOTSTRAP_REQUIRED and the exact commands to run:

{"code":"BOOTSTRAP_REQUIRED","instructions":[
  "spl service-account create --bootstrap --name admin --scopes admin --with-token",
  "..."
]}

See First run and Service accounts.

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