GuideSeptember 29, 20267 min read

Self-Hosting ConfigSync: Run Your Own Sync Server

ConfigSync's CLI is open source and supports custom API endpoints. Here is how to run your own sync server for full data sovereignty and control.

Why Self-Host?

The hosted ConfigSync service at configsync.dev handles everything — infrastructure, updates, availability, and scaling. For most developers and teams, it is the right choice. But some organizations have constraints that a hosted service cannot satisfy.

Data sovereignty requirements may mandate that all data stays within a specific country or on-premises network. Regulatory compliance may require audit logs with specific retention policies. Air-gapped environments may have no internet access at all. For these scenarios, self-hosting is the answer.

Pointing the CLI at Your Server

The ConfigSync CLI accepts a custom API URL. Once configured, all operations use your server:

Custom API endpoint

# Authenticate against your own server configsync login --api-url https://sync.yourcompany.com --token cs_xxx # Verify the connection configsync status # Server: sync.yourcompany.com # User: sean@company.com # Machines: 5 # All commands now use your server configsync push # → https://sync.yourcompany.com/api/machines/snapshot configsync pull # → https://sync.yourcompany.com/api/machines/snapshot

The --api-url setting persists in your local configuration file. You set it once and every subsequent command routes to your server automatically.

The API You Need to Implement

ConfigSync's API surface is intentionally small. You need to implement six endpoints:

Endpoint	Method	Purpose
/api/auth/login	POST	Authenticate user, return JWT token
/api/machines	GET	List registered machines
/api/machines	POST	Register a new machine
/api/machines/snapshot	POST	Receive encrypted state (push)
/api/machines/snapshot	GET	Serve encrypted state (pull)
/api/machines/history	GET	List previous push snapshots

Zero knowledge by design: Your server stores encrypted blobs. It never needs to decrypt user data. All encryption and decryption happens client-side with the user's master password. Even if your server is compromised, the stored data is useless without each user's key.

Using the Reference Implementation

The configsync-web project (this website and API) is the reference implementation. You can fork it and deploy to your own infrastructure:

Deployment options

# Option 1: Deploy to your Cloudflare account # Fork github.com/InventiveHQ/configsync-web # Set up D1 database and R2 storage in your Cloudflare account # Configure bindings and deploy via wrangler npx wrangler d1 create configsync-db npx wrangler r2 bucket create configsync-states npx wrangler secret put JWT_SECRET npx wrangler deploy # Option 2: Adapt for traditional hosting # Replace D1 with PostgreSQL or MySQL # Replace R2 with S3, MinIO, or local filesystem # Deploy as a Node.js application behind nginx # Option 3: Build from scratch # Implement the 6 API endpoints in any language # Store user metadata in any database # Store encrypted snapshots in any object storage

Infrastructure Requirements

A self-hosted ConfigSync deployment needs three components:

Minimum infrastructure

# Compute: any web server # - Node.js, Python, Go, Rust — your choice # - Handles JWT auth and routes API requests # Database: user and machine metadata # - PostgreSQL, MySQL, or SQLite # - Schema: users, machines, api_tokens, state_snapshots # - Reference schema in configsync-web/schema.sql # Object Storage: encrypted state snapshots # - S3-compatible (AWS S3, MinIO, Backblaze B2) # - Or simple filesystem storage for small deployments # - Each snapshot is a single encrypted blob per user

For a small team (under 20 developers), a single VM with SQLite and filesystem storage is sufficient. The encrypted snapshots are typically a few megabytes per user. For larger deployments, use a managed database and S3-compatible storage.

Benefits and Tradeoffs

Factor	Self-Hosted	Hosted (configsync.dev)
Data location	Your servers/network	Cloudflare global network
Maintenance	Your responsibility	Fully managed
Customization	Full control	Standard configuration
Network access	Can be internal-only	Requires internet
Cost	Your infrastructure costs	Free tier available
Uptime	Your SLA	Managed availability

Self-hosting gives you complete control at the cost of operational overhead. You handle backups, updates, monitoring, and availability. For organizations with strict compliance requirements or air-gapped networks, this tradeoff makes sense. For everyone else, the hosted service removes the operational burden so you can focus on development.

Ready to try ConfigSync?

Sync your entire dev environment across machines in minutes. Free forever for up to 3 devices.

Get Started Read the Docs