Running Connect as a Daemon / OS Service
This page covers two related but distinct "long-running process" concerns: running the Agent as an
OS-managed background service (systemd, launchd, Windows service), and operating the connect server
binary as a long-running daemon process. For deployment topologies, observability, secret handling, and
containerised deployment, see Production Operations — this page doesn't duplicate
that content.
Neither connect agent nor connect server daemonizes itself. Both are ordinary foreground processes that log
to stdout (or a file, via log.file) and run until they receive a termination signal. Running either
long-term means putting a process supervisor in front of it — this page shows what's shipped for that today.
Running today
connect agent and connect server are distributed as:
- Standalone binaries and
apk/deb/rpmpackages (built vianfpm). - A Homebrew formula (
dioad/homebrew-tap). - Docker images (
dioad/connect) — see Production Operations §1.3 for the containerised path, which already handles process supervision via your container runtime/orchestrator.
deb / rpm — systemd
The deb and rpm packages install two systemd units, connect-agent.service and connect-server.service
(source of truth: packaging/systemd/connect-agent.service
and connect-server.service
in the repo). Both run under
DynamicUser=yes — systemd allocates a transient, unprivileged UID/GID per run and owns a StateDirectory
(/var/lib/connect-agent / /var/lib/connect-server) for them, so there's no fixed connect system account to
create or manage.
Installing the package does not enable or start either unit automatically. To run one:
$ systemctl enable --now connect-agent.service
connect-agent.service checks its config before each start. If agent.yaml exists, ExecStartPre runs
connect agent config validate, so a bad edit fails once with the reason in journalctl -u connect-agent rather
than restarting every five seconds. The unit also drops every capability and restricts system calls, address
families and kernel interfaces; plugins and exec processes such as maddy run under the same limits. An exec
process that must bind a port below 1024 needs the drop-in described in the unit file. TimeoutStopSec=45 allows
for the agent's default 30s shutdown when exec processes run: raise it if you raise shutdown-timeout.
connect-agent.service needs no config file prepared first. connect agent self-bootstraps a minimal one
(just management.listen-address, bound to loopback) the first time it runs with none — the unit's
CONNECT_AGENT_CONFIG_FILE=/var/lib/connect-agent/agent.yaml environment variable points this at the service's
own writable StateDirectory rather than /etc, which ProtectSystem=strict doesn't allow the service to write
to. Once running, the management interface's first-run setup wizard (create a local admin account, then agent
identity) is reachable at http://127.0.0.1:4444/ui over an SSH port-forward to that address on the host.
Tunnels still need connect agent init or manual editing of /var/lib/connect-agent/agent.yaml — the wizard
covers admin access and identity, not tunnel authoring.
The service's status file is under its state directory, readable only by the
service's user. Read it as root, pointing connect agent status at the service's config:
$ sudo connect agent status --config /var/lib/connect-agent/agent.yaml --status-directory /var/lib/connect-agent/.config/dioad/connect/status.d
If you'd rather manage the config file yourself (a config-management tool, or /etc/dioad/connect/agent.yaml
specifically) instead of the self-bootstrapped default, override both variables via a drop-in:
$ systemctl edit connect-agent.service
[Service]
Environment=CONNECT_AGENT_CONFIG_FILE=/etc/dioad/connect/agent.yaml
ReadWritePaths=/etc/dioad/connect
(ReadWritePaths= is required — ProtectSystem=strict otherwise blocks the write even with the path pointed
there.) Any other field is already overridable this way too, without a drop-in for the path itself — e.g.
Environment=CONNECT_MANAGEMENT_LISTEN_ADDRESS=0.0.0.0:4444 — since connect agent binds config values from
the environment (CONNECT_<FIELD>) before the config file, same as any other CLI flag it exposes.
connect-server.service is unchanged: it still needs /etc/dioad/connect/server.yaml written before
systemctl enable --now (connect server config example lists every setting it can have), and keeps its ConditionFileNotEmpty= gate, so an
enabled-but-unconfigured unit skips cleanly at boot instead of crash-looping.
identity.token-file and the default ~/.config path
If you rely on the agent's default identity.token-file (~/.config/dioad/connect/auth.yaml), set it to a
flat path under the service's state directory instead:
identity:
token-file: /var/lib/connect-agent/auth.yaml
StateDirectory= only pre-creates the state directory itself, not a .config/dioad/connect/ subtree under
it, and the token save path doesn't create its parent directory — so the default ~-relative path won't
persist a token under the sandboxed service account. The ACME cache-directory: .autocert default doesn't
have this problem and needs no adjustment.
apk — no service integration
The apk package (Alpine Linux) ships the binary and README.md only, same as before — no unit file, no
install scripts. Alpine uses OpenRC, not systemd, so a systemd unit wouldn't apply; if you need OS-service
integration on Alpine, adapt connect-agent.service's shape (single foreground process, restart-on-failure) into
an OpenRC init.d script.
Homebrew — launchd
connect agent (only) has native brew services integration via the formula's service block:
$ mkdir -p "$(brew --prefix)/etc/dioad/connect"
$ connect agent init --output-file "$(brew --prefix)/etc/dioad/connect/agent.yaml"
# edit the config file to suit your environment
$ brew services start connect
connect server has no brew service (a formula supports exactly one service block, and brew installs are the
individual/dev-machine use case — connect server is the self-hosted infra binary, covered by Docker or the
systemd units above). For connect server on macOS, or for connect agent installed from the raw release
archive rather than Homebrew, use the manual launchd templates at
packaging/launchd/net.dioad.connect.agent.plist
and net.dioad.connect.server.plist
— copy the one you need to ~/Library/LaunchAgents/ and launchctl load -w it, adjusting the paths inside to
match your install location.
connect server as a daemon
Beyond generic process-supervision (above), a few things are specific to running connect server long-term:
- Log rotation is handled in-process via the
log.max-size,log.max-backups,log.max-age, andlog.compresskeys — see Server Configuration Reference §log. There's no need for external rotation (e.g.logrotate) unless you prefer to manage it that way. - Restart-on-failure is your supervisor's job (
Restart=on-failurein the systemd unit above, or your orchestrator's restart policy in a containerised deployment) — the server has no built-in self-restart. - High availability is a self-hosted limitation, not a daemon-supervision one — see Production Operations §1.2 for the hosted-vs-self-hosted distinction.