IPC Endpoints

v0.5.7 Litestream exposes IPC (Inter-Process Communication) endpoints via a Unix domain socket. These endpoints allow local tools and scripts to query database status and collect profiling data without exposing an HTTP port.

Enabling the Socket#

The control socket is disabled by default. Enable it with a socket block in your configuration file:

socket:
  enabled: true            # default: false
  path: /var/run/litestream.sock
  permissions: 0600

The path defaults to /var/run/litestream.sock and permissions defaults to 0600.

Once enabled, the socket is created when the Litestream daemon starts and removed on shutdown. The CLI commands and curl examples below assume the default path; pass -socket <path> (or --unix-socket <path>) if you changed it.

Endpoints#

GET /list#

Returns all databases currently tracked by the Litestream daemon, along with their last sync time.

Example:

$ curl --unix-socket /var/run/litestream.sock \
    http://localhost/list
{"databases":[{"path":"/path/to/my.db","status":"replicating","last_sync_at":"2026-02-12T00:00:00Z"}]}

Status values:

CLI equivalent: litestream list -socket /var/run/litestream.sock

GET /info#

Returns information about the running Litestream daemon including version, PID, and uptime.

Example:

$ curl --unix-socket /var/run/litestream.sock \
    http://localhost/info
{"version":"0.5.8","pid":12345,"uptime_seconds":3600,"started_at":"2026-02-12T00:00:00Z","database_count":1}

POST /register#

Dynamically registers a new database with the Litestream daemon without restarting.

Request body (JSON):

Example:

$ curl --unix-socket /var/run/litestream.sock \
    -X POST http://localhost/register \
    -H "Content-Type: application/json" \
    -d '{"path":"/path/to/my.db","replica_url":"s3://mybucket/my.db"}'

CLI equivalent: litestream register -socket /var/run/litestream.sock -replica s3://mybucket/my.db /path/to/my.db

POST /unregister#

Dynamically unregisters a database from the Litestream daemon without restarting.

Request body (JSON):

Example:

$ curl --unix-socket /var/run/litestream.sock \
    -X POST http://localhost/unregister \
    -H "Content-Type: application/json" \
    -d '{"path":"/path/to/my.db"}'

CLI equivalent: litestream unregister -socket /var/run/litestream.sock /path/to/my.db

POST /start#

Starts replication for a database that is registered but stopped, without restarting the daemon.

Request body (JSON):

Example:

$ curl --unix-socket /var/run/litestream.sock \
    -X POST http://localhost/start \
    -H "Content-Type: application/json" \
    -d '{"path":"/path/to/my.db"}'
{"status":"started","path":"/path/to/my.db","txid":42}

Response statuses:

CLI equivalent: litestream start -socket /var/run/litestream.sock /path/to/my.db

POST /stop#

Stops replication for a database without unregistering it or restarting the daemon.

Request body (JSON):

Example:

$ curl --unix-socket /var/run/litestream.sock \
    -X POST http://localhost/stop \
    -H "Content-Type: application/json" \
    -d '{"path":"/path/to/my.db"}'
{"status":"stopped","path":"/path/to/my.db","txid":42}

Response statuses:

CLI equivalent: litestream stop -socket /var/run/litestream.sock /path/to/my.db

GET /txid#

Returns the current transaction ID for a database.

Query parameters:

Example:

$ curl --unix-socket /var/run/litestream.sock \
    "http://localhost/txid?path=/path/to/my.db"
{"txid":42}

POST /sync#

v0.5.9 Forces an immediate WAL-to-LTX sync for a database. Without wait, the sync is triggered and the request returns immediately (fire-and-forget). With wait set to true, the request blocks until both local and remote replication complete.

Request body (JSON):

Example (fire-and-forget):

$ curl --unix-socket /var/run/litestream.sock \
    -X POST http://localhost/sync \
    -H "Content-Type: application/json" \
    -d '{"path":"/path/to/my.db"}'
{"status":"synced_local","path":"/path/to/my.db","txid":42,"replicated_txid":40}

Example (blocking):

$ curl --unix-socket /var/run/litestream.sock \
    -X POST http://localhost/sync \
    -H "Content-Type: application/json" \
    -d '{"path":"/path/to/my.db","wait":true,"timeout":60}'
{"status":"synced","path":"/path/to/my.db","txid":42,"replicated_txid":42}

Response fields:

Response statuses:

CLI equivalent: litestream sync -socket /var/run/litestream.sock /path/to/my.db

GET /debug/sync-status#

v0.5.12 Returns detailed sync diagnostics for the databases tracked by the daemon. This is useful for observing in-progress sync and checkpoint operations. Without the path parameter, diagnostics for all databases are returned.

Query parameters:

Example (all databases):

$ curl --unix-socket /var/run/litestream.sock \
    http://localhost/debug/sync-status
{"databases":[{"path":"/path/to/my.db","active":true,"operation":"sync","phase":"write_ltx_from_wal","started_at":"2026-02-12T00:00:00Z","updated_at":"2026-02-12T00:00:01Z","elapsed_seconds":1.2,"txid":42,"wal_size":32768,"last_synced_wal_offset":16384}]}

Example (single database):

$ curl --unix-socket /var/run/litestream.sock \
    "http://localhost/debug/sync-status?path=/path/to/my.db"

Response fields:

Each entry in databases contains the following fields. path and active are always present; the remaining fields are omitted when empty or zero. When active is false, the operation-specific fields describe the most recently completed operation rather than work in progress.

/debug/pprof/*#

Standard Go pprof endpoints for runtime profiling. These allow you to collect CPU profiles, heap snapshots, and goroutine dumps without running a separate HTTP server.

CPU profile:

$ curl --unix-socket /var/run/litestream.sock \
    http://localhost/debug/pprof/profile > cpu.pprof

Heap profile:

$ curl --unix-socket /var/run/litestream.sock \
    http://localhost/debug/pprof/heap > heap.pprof

Goroutine dump:

$ curl --unix-socket /var/run/litestream.sock \
    "http://localhost/debug/pprof/goroutine?debug=2"

Available pprof paths:

Use go tool pprof to analyze collected profiles:

go tool pprof cpu.pprof
go tool pprof heap.pprof

See Also#

• Configuration Reference - Complete configuration options
• Metrics - Prometheus metrics reference