Environment variables
Operational knobs for headless, server, and multi-profile deployments.
Most users never set these — the desktop app and the
--profile flag cover the common cases. They matter
mainly for headless servers, containers, and running more than one instance on
a single machine. Values are read once at startup, so set them before launching
uniclip (or the GUI).
| Variable | Effect |
|---|
UC_PROFILE | Run under a named profile, isolating the data dir, log dir, keychain entry, and iroh identity. The environment equivalent of --profile. For example UC_PROFILE=dev stores under app.uniclipboard.desktop-dev. |
| Variable | Effect |
|---|
UC_DISABLE_SYSTEM_CLIPBOARD | When set, the daemon never reads or writes the OS clipboard; it still syncs over iroh as a normal member. Linux hosts without a graphical session (neither DISPLAY nor WAYLAND_DISPLAY set) disable the clipboard automatically and start as usual, so this variable is mainly for force-disabling on a desktop. |
UC_DAEMON_RUN_MODE | Spawn contract for the background daemon: server selects the headless server-node mode (which also disables the system clipboard). From the terminal prefer uniclip start --server, which sets it for you. |
UC_HOST_ROLE | Diagnostics role label for this process — gui-host, daemon, or cli — used in error/telemetry attribution. Normally set automatically; override only to relabel events. |
| Variable | Effect |
|---|
UC_IROH_BIND_PORT | Pin the local iroh UDP port instead of letting the OS assign one — handy when you need a stable port to forward through a firewall or NAT. |
UC_IROH_PUBLIC_ADDR | Advertise a specific public address for this node, for hosts behind static NAT or with a known public IP. Typically paired with UC_IROH_BIND_PORT. |
UC_CONGESTION_CONTROLLER | Override the QUIC congestion controller without opening the settings UI. Accepts cubic (default) or bbr3. Useful for quick A/B testing on headless nodes. Requires a daemon restart. |
| Variable | Effect |
|---|
RUST_LOG | Standard tracing filter; overrides UC_LOG_PROFILE when set. Accepts a level (RUST_LOG=debug) or per-module directives (RUST_LOG=uniclip=debug,iroh=info). |
UC_LOG_PROFILE | Select a logging preset — dev, prod, debug_clipboard, or cli. Defaults to dev on debug builds and prod on release builds. |
UC_LOG_FILE | Diagnostics only: write JSON logs to this one exact file, with no daily rotation and no retention pruning. Daemon-only — the value must be an absolute path and UC_HOST_ROLE must be daemon, or startup fails outright, so two roles can never append to the same file. Leave unset for the normal per-role, per-day rolling logs. |
For everyday setup see Install and
Self-host a relay. The binary's --help and the
source remain the authoritative reference for accepted values and defaults.