Syncthing
Encrypted, peer-to-peer file synchronization with a per-user QuickBox service
Overview
Syncthing continuously synchronizes files between devices using encrypted, peer-to-peer connections. On QuickBox Pro it runs as a per-user systemd service, binds to the loopback interface, and is reverse-proxied through nginx.
It is not a cloud backup service—changes propagate to all peers, so deletions and edits replicate across your mesh.
Key features
Syncthing on QuickBox ships with per-user isolation, hardened service settings, and a pre-built nginx reverse proxy for the web UI.
🧩 Per-user binary & service
Runs as <code>syncthing@username</code> via <code>/opt/username/Syncthing/syncthing serve</code> with ProtectSystem, PrivateTmp, MemoryDenyWriteExecute, and NoNewPrivileges enabled.🔒 Loopback-bound UI
Installer rewrites <code>config.xml</code> to listen on <code>127.0.0.1:8384</code> (or the auto-assigned port) and pairs it with nginx basic auth at <code>/username/syncthing/</code>.🗂️ Config & API key managed
Stores UI/API settings in <code>/home/username/.config/Syncthing/config.xml</code>; dashboard surfaces the API key and port directly from that file.🚦 Port auto-assignment
Defaults to port <code>8384</code> with automatic allocation if occupied; nginx proxy and system database both track the chosen port.When to use it
Use Syncthing when you need device-to-device sync without centralized storage; avoid it if you need one-way backups or object storage semantics.
Good fit
- You want real-time folder sync between servers without exposing services beyond localhost.
- You need per-user isolation with QuickBox-managed ports and API keys.
- You prefer a browser UI proxied behind QuickBox authentication instead of direct LAN exposure.
What QuickBox provides
- QuickBox installs Syncthing to /opt/username/Syncthing and runs syncthing@username with a loopback-bound UI.
- nginx proxy at /username/syncthing/ enforces HTTP basic auth via /etc/htpasswd.d/htpasswd.username.
- Port and API key are stored in /home/username/.config/Syncthing/config.xml and shown on the dashboard service card.
Installation
Install from the QuickBox CLI
Use the standard software lifecycle commands; the installer downloads the latest Syncthing release tarball, seeds config, and registers the systemd unit and nginx proxy.
CLI options
-u, --usernameRequiredTarget QuickBox user for install, update, reinstall, or remove.
qb install syncthing -u usernameInstall from the Dashboard
The dashboard service cards list Syncthing with Install/Reinstall/Remove controls; once installed, the card shows the current port and API key and links to launch the UI.
Access and authentication
URL / route
nginx publishes the UI at https://server/username/syncthing/, proxying to http://127.0.0.1:port/ (port defaults to 8384 and is stored per user). The proxy config lives at /etc/nginx/software/username.syncthing.conf and is templated by the installer.
Login / credentials / tokens
- HTTP basic auth uses the per-user htpasswd at
/etc/htpasswd.d/htpasswd.username. - Syncthing’s API/UI key is written to
/home/username/.config/Syncthing/config.xml(<apikey>), and the dashboard exposes it in the service card.
Security notes
- The systemd unit
syncthing@usernameruns as the target user with ProtectSystem=full, PrivateTmp=true, MemoryDenyWriteExecute=true, and NoNewPrivileges=true. - The UI binds to 127.0.0.1 only; nginx handles external access under
/username/syncthing/.
Configuration and files
Syncthing writes its config after the first start; the installer waits for config.xml, rewrites the listen address to the chosen port, and normalizes permissions to 0664.
Common tasks
- Start/stop via systemd:
systemctl start syncthing@username,systemctl stop syncthing@username(service file lives at/etc/systemd/system/syncthing@.service). - View status/logs:
systemctl status syncthing@usernameandjournalctl -u syncthing@username -f. - Update to latest release:
qb update syncthing -u username(pulls the current upstream tarball and restarts the service). - Reinstall while preserving ports and config:
qb reinstall syncthing -u username. - Confirm UI port/API key: dashboard service card shows both; they are sourced from
config.xml.
FAQ
Best practices
Do
- Access the UI through https://server/username/syncthing/ so nginx basic auth and TLS stay in place.
- Use qb update syncthing -u username to pull the latest signed release tarball.
- Keep config.xml under versioned backups if you customize devices/folders heavily; QuickBox already copies it into the software backup set during install.
Don't
- Avoid exposing 127.0.0.1:port directly to the network; the service is intended to stay loopback-bound.
- Do not delete /etc/nginx/software/username.syncthing.conf or the htpasswd file; they guard access to the UI.
Troubleshooting
UI not reachable
Symptom: /username/syncthing/ returns 502 or times out. Checks: ensure systemctl status syncthing@username is active, confirm the port in /etc/nginx/software/username.syncthing.conf matches the one in config.xml, then reload nginx with systemctl reload nginx.
API key missing in dashboard
Symptom: API field is blank. Checks: verify <apikey> exists in /home/username/.config/Syncthing/config.xml; if absent, restart the service to regenerate, then refresh the dashboard card to pull the latest value.
Resources
Syncthing resources
Join the Community
Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.