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 binaries (skip either command if already installed).
# 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
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 --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. 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.
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 run it under a supervisor:
# /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).
[]
= "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 |
TLS_ENABLED=true |
Acknowledge TLS termination by a reverse proxy |
METRICS_USERNAME / METRICS_PASSWORD |
Enable authenticated /metrics |
CORS_ALLOWED_ORIGINS |
Comma-separated allowed origins |
CORS_ALLOW_ALL=true |
Allow all CORS origins (development only) |
/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 SNIP_SYNC_ALLOW_HTTP=false /home/user/.cargo/bin/snip-sync croncheck
*/5 * * * * TLS_ENABLED=true SNIP_SYNC_ALLOW_HTTP=false /home/user/.cargo/bin/snip-sync croncheck
Use systemd or another real supervisor for production. 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 is automatic for Cargo-managed installations. Homebrew,
Docker, and source-built binaries should be updated through the tool that
installed or built them.
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 an OS keychain. On a deliberately headless machine,
SNP_ALLOW_PLAINTEXT_API_KEY=true snp register ...opts into plaintext storage and should be protected with strict file permissions. - 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.