Skip to content

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/rpm packages (built via nfpm).
  • 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, and log.compress keys — 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-failure in 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.