snip-sync server
snip-sync is the optional, self-hostable gRPC server used by the snp client.
Snippet descriptions, commands, and tags are encrypted by the client before
upload; the server stores ciphertext plus the metadata needed to synchronize
libraries.
snip-sync deliberately does not terminate TLS. It serves plaintext gRPC and
HTTP, normally on loopback, and should sit behind a TLS-terminating reverse
proxy for a remote deployment. TLS_ENABLED=true only acknowledges that an
upstream proxy is providing TLS; it does not turn on TLS inside snip-sync.
Local quickstart
This is the shortest path for trying the client and server on one machine.
# Install both verified release binaries (skip either command if already installed).
|
# Cargo is the source/package fallback when a host has no prebuilt asset.
# cargo install snip-it snip-sync
# Create the platform-specific config, database, state, and data directories.
# Certificates are not needed for direct loopback development.
# Keep this in a terminal while using the client.
SNIP_SYNC_ALLOW_HTTP=true
The bootstrap installer initializes missing server layout/config without overwriting existing data. On releases containing the lifecycle installer, register startup with the server itself so the appropriate supervisor is selected for the host:
Startup registration is intentionally owned by snip-sync; the binary
installer does not duplicate systemd, launchd, cron, or Task Scheduler
templates. If an older installed binary does not expose startup, upgrade it
or follow the manual supervisor examples below.
In another terminal, register the client and sync:
Registration creates the account, stores the server URL and device ID in the
client config, and stores the API key in the OS keychain when available. Run
snp register --force only when you intentionally want a new account and key;
it does not join an existing account.
For multiple environments, register once, then securely provision that same
API key, server URL, and a unique device ID to each environment that should
share the libraries. Registering each environment independently creates
isolated accounts. After the first client seeds the server, use
snp sync run --pull-only on new environments and then set
sync_direction = "Bidirectional" in the client sync.toml for normal use.
See USER_GUIDE.md
for the client-side settings example.
The server config location is platform-specific. Run this to see the exact paths in use:
The server defaults to gRPC 127.0.0.1:50051, HTTP health/metrics
127.0.0.1:50050, and a SQLite database under the platform data/config area.
The initialized premade directory is also shown by snip-sync paths.
Lifecycle commands
Use snip-sync stop to stop the local server and snip-sync restart to stop
and start it again. If startup registration exists, restart delegates to
that manager and performs a bounded health check. On Unix, both commands
accept the current structured PID record and older numeric PID files. A dead
numeric PID is cleaned only after the server singleton lock is acquired; a
live process whose name is not snip-sync is refused unless --force is
supplied. The persistent
snip-sync.server.lock file may remain after shutdown because its kernel lock,
not file existence, records ownership.
Register boot startup with the server itself. instructions is read-only and
prints the exact rendered unit, plist, cron block, or Task Scheduler commands:
Auto mode selects a running systemd host on Linux, cron otherwise, launchd on
macOS, and Task Scheduler on Windows. Systemd and launchd installation use
the intended non-root account and print an exact sudo command when elevation
is needed; they never silently fall back to cron. Cron and Task Scheduler
invoke croncheck, not serve directly. Startup registration persists only
small manager metadata under the state directory and never removes the
binary, database, configuration, certificates, or premade libraries.
To generate local certificate assets for a reverse-proxy experiment:
This writes cert.pem and key.pem under the reported certificate directory.
They are self-signed development assets for a proxy, not production
certificates, and are not read directly by snip-sync.
Production deployment
Use a real certificate from a trusted CA at the reverse proxy and forward gRPC
over cleartext HTTP/2 (h2c) to the loopback server. For example, Caddy can
use:
sync.example.com {
reverse_proxy h2c://127.0.0.1:50051
}
Keep the server bound to loopback in snip-sync and register it with the
appropriate supervisor:
For manual systemd execution, the equivalent unit is:
# /etc/systemd/system/snip-sync.service
[Unit]
Description=snip-sync gRPC server
After=network.target
[Service]
Type=simple
User=snip-sync
ExecStart=/usr/local/bin/snip-sync serve
Environment=CONFIG_PATH=/etc/snip-sync/config.toml
Environment=TLS_ENABLED=true
Environment=DATABASE_URL=/var/lib/snip-sync/snippets.db
Environment=PREMADE_DIR=/var/lib/snip-sync/premade-libraries
Restart=on-failure
[Install]
WantedBy=multi-user.target
TLS_ENABLED=true is appropriate here because the proxy terminates TLS. The
server process itself remains plaintext and should not be exposed directly to
the public network.
Register the client using the proxy's HTTPS URL, not the backend port:
The client uses the operating system's trusted certificate roots for HTTPS, so
use a publicly trusted certificate for a remote deployment. A self-signed
certificate generated by snip-sync cert is intended for local proxy testing.
Configuration
The default config path is the platform config directory shown by
snip-sync paths. Set CONFIG_PATH to use a specific file:
CONFIG_PATH=/etc/snip-sync/config.toml
Configuration priority is environment variables, then the TOML file, then compiled defaults. The generated file contains the common settings:
An existing configuration file is fail-closed: malformed TOML or an unreadable file stops startup with an error naming the path. Defaults are used only when the configuration file is missing (and the normal bootstrap path may create it).
Environment variable overrides are strictly parsed: a present but invalid value
(e.g., a non-numeric port) causes startup to fail with an error naming the
variable and the supplied value. Boolean environment variables accept
case-insensitive true, 1, yes, on and false, 0, no, off;
unknown values fail instead of silently falling back. Range validation rejects
operationally nonsensical values (e.g., zero ports, zero connection limits).
[]
= "127.0.0.1"
= 50051
= "127.0.0.1"
= 50050
[]
# path = "/var/lib/snip-sync/snippets.db"
[]
# directory = "/var/lib/snip-sync/premade-libraries"
[]
= 1024
= 1024
= 50
= 100
= 30
[]
= 120
[]
# username = "metrics"
# password = "change-me"
[]
= ""
Important environment variables:
| Variable | Purpose |
|---|---|
GRPC_HOST / GRPC_PORT |
gRPC bind address |
HTTP_HOST / HTTP_PORT |
Health and metrics bind address |
DATABASE_URL |
SQLite file path (not a remote database URL) |
PREMADE_DIR |
Premade library directory |
CONFIG_PATH |
Config file override |
SNIP_SYNC_ALLOW_HTTP=true |
Explicit local plaintext mode (boolean: true/1/yes/on) |
TLS_ENABLED=true |
Acknowledge TLS termination by a reverse proxy (boolean: true/1/yes/on) |
METRICS_USERNAME / METRICS_PASSWORD |
Enable authenticated /metrics |
CORS_ALLOWED_ORIGINS |
Comma-separated allowed origins |
CORS_ALLOW_ALL=true |
Allow all CORS origins, development only (boolean: true/1/yes/on) |
/health is unauthenticated and returns HTTP 200 only when the database is
reachable. /metrics is disabled unless both metrics credentials are set.
Supervision fallback
croncheck is a lightweight fallback for hosts without systemd. It checks the
actual /health response and starts one detached server when needed. For a
production reverse-proxy deployment, use:
@reboot TLS_ENABLED=true /home/user/.cargo/bin/snip-sync croncheck
*/5 * * * * TLS_ENABLED=true /home/user/.cargo/bin/snip-sync croncheck
Prefer snip-sync startup install --method cron so these entries are
idempotent and owned lines can be removed safely. SNIP_SYNC_ALLOW_HTTP=true
is only generated for loopback binds; non-loopback startup requires the
explicit TLS_ENABLED=true acknowledgement. croncheck is not a
replacement for service logging, restart policies, or privilege management.
Other commands
snip-sync cert uses the system openssl command. It refuses to overwrite
existing assets unless --force is supplied and preserves existing assets if
certificate generation fails.
snip-sync update selects the stable snip-sync version from crates.io and
uses the exact matching, SHA-256-verified GitHub binary on supported hosts.
Bootstrap, Cargo, and directly managed executables use the same path; source-
only targets and a definite release-asset 404 use an exact-version Cargo
fallback staged before replacement. Checksum, transport, and candidate
identity failures are hard failures and never fall back to Cargo. A running
server is restarted through its registered manager (or the direct lifecycle),
while an intentionally stopped or inactive server remains stopped. If restart
fails after replacement, the command reports the partial activation and the
manual snip-sync restart recovery command.
Source build and Docker
For contributors building from the repository:
For a container image:
The container example exposes plaintext gRPC and should likewise be placed behind a TLS proxy before being exposed publicly. When the proxy runs on the host, bind the published ports to loopback:
The repository's docker-compose.yml is useful for
local/container-network deployments. Review its port bindings before using it
on a remote host.
Troubleshooting
TLS termination is required: useSNIP_SYNC_ALLOW_HTTP=trueonly for a local direct connection, or put a TLS proxy in front and setTLS_ENABLED=true.- Client registration fails: use
http://127.0.0.1:50051for direct local serving and the proxy'shttps://URL for production. - A second environment sees no libraries: it was probably registered as a new account. Provision the first environment's API key instead.
- API key cannot be saved: configure a supported OS keychain. Snip-it refuses to write the API key as plaintext when the keychain is unavailable.
- Port in use: run
snip-sync pathsand inspect the configured gRPC/HTTP ports. - Health check fails: request
curl http://127.0.0.1:50050/healthand inspect the server logs. - Server will not stop: use
snip-sync stop --forceonly after confirming the PID withsnip-sync pathsand the process list.