loginctl enable-linger: keep an agent's user service running
Why a systemd user service stops when you log out of SSH and is missing after a reboot, how to turn lingering on and check it, and the su bus error.
A systemd user service runs inside your account’s own service manager, and without lingering that manager exists only while you are logged in: it starts at your first login, stops about ten seconds after your last session ends, and is not started at boot. That is why an agent’s gateway or server installed as a user service dies when you close SSH and is missing after a reboot. Turn lingering on once, then check it:
sudo loginctl enable-linger "$USER"
loginctl show-user "$USER" --property=Linger # Linger=yesCopiedThe setting is a file in /var/lib/systemd/linger/, so it survives reboots, and from then on the services you enabled with systemctl --user enable start at boot and keep running with nobody logged in.
Why a user service is tied to your login
On a systemd machine every account can have its own service manager, the user@.service instance, and systemctl --user talks to it. By default the login itself is what starts it. In the pam_systemd manual, logging in starts that instance, and “if the last concurrent session of a user ends, the user’s systemd instance will be terminated too.” The stop is not instant: logind keeps it for UserStopDelaySec=, which “defaults to 10s”, so a quick reconnect finds it still there. Every service it runs stops with it.
Lingering removes the dependence on a login. The loginctl manual: “If enabled for a specific user, a user manager is spawned for the user at boot and kept around after logouts. This allows users who are not logged in to run long-running services.” Without it, an enabled user service does start, but only when you SSH in, which is how a gateway can look healthy all afternoon and then be gone overnight.
Turning it on, and checking it
sudo loginctl enable-linger alice # another account, or your own
loginctl enable-linger # your own account, no argument
loginctl show-user alice --property=Linger
ls /var/lib/systemd/linger/ # one empty file per lingering user
sudo loginctl disable-linger alice # undoCopiedEnabling it for your own account needs no sudo under systemd’s default policy, which allows a user to set it on themselves; for anyone else it asks for an administrator. The command writes the file and starts that user’s manager at once, so nothing waits for a reboot: services already enabled for the account start right away.
The file is the more reliable check. loginctl show-user asks about a user logind currently knows, so for an account that is neither logged in nor lingering it prints no property, only:
Failed to get user: User ID 1001 is not logged in or lingeringCopiedThat message is itself the answer: lingering is off for that account and its user services are not running.
A minimal user unit for an agent’s server
The agents that install their own service write a unit like this for you. For one that does not, or a server your agent built, a unit goes in ~/.config/systemd/user/:
# ~/.config/systemd/user/agent-server.service
[Unit]
Description=Agent server
[Service]
WorkingDirectory=%h/agent
ExecStart=%h/.local/bin/agent-server --port 8080
Restart=on-failure
[Install]
WantedBy=default.targetCopiedsystemctl --user daemon-reload
systemctl --user enable --now agent-server.service
systemctl --user status agent-server.service
journalctl --user -u agent-server.service -fCopiedThree lines carry most of it. WantedBy=default.target ties the service to the user manager’s main target, “started by default when the service manager is invoked”, so with lingering on it starts at boot. ExecStart needs the program’s full path: systemd does not read your shell’s PATH, and a bare name is looked up only in system directories such as /usr/local/bin/ and /usr/bin/, so a tool installed in ~/.local/bin is not found. %h is your home directory. And Restart=on-failure is what the service manual calls “the recommended choice for long-running services”. The logs are in your user journal, which is why plain journalctl -u without --user shows nothing for a user unit.
What each agent installs
- OpenClaw.
openclaw onboard --install-daemonoropenclaw gateway installwrites a user unit,openclaw-gateway.service(with a profile suffix for named profiles). Its onboarding reference says the wizard “attemptsloginctl enable-linger <user>so gateway stays up after logout” and “tries without sudo first”, so check the result rather than assume it. Logs:journalctl --user -u openclaw-gateway -f. Stopping it for good is covered in restarting and stopping OpenClaw. - Hermes.
hermes gateway installwrites the user unithermes-gateway, and Nous’s messaging page pairs it withsudo loginctl enable-linger $USER. It also offers a system service,sudo hermes gateway install --system, “on VPS or headless hosts that should come back at boot without relying on systemd linger”; one or the other, not both, as installing Hermes explains. - OpenCode 2. Its background service is not a systemd unit. The first
opencodecommand starts it detached; on 2.1.2 on Ubuntu 24.04 it outlived the SSH session that started it, and after a reboot nothing ran until a client started it again. Lingering changes neither. For a server that must come up at boot, OpenCode’s web page points toopencode serve, which runs “in the foreground instead of through the shared background service” for “a supervisor like systemd”, withOPENCODE_PASSWORDset for a fixed password; that is a unit like the one above. OpenCode’s background service covers the rest. - Claude Code and Codex have no gateway to keep running, but an unattended run started by a systemd user timer needs lingering exactly as a service does, as running them on a schedule describes.
“Failed to connect to bus” after su or sudo
Switch to the agent’s account with sudo su - alice or sudo -u alice and any systemctl --user command fails. On Ubuntu 24.04, which ships systemd 255, it prints:
Failed to connect to bus: No medium foundCopiedsystemd 257 and later say the same thing more helpfully:
“Failed to connect to user scope bus via local transport: $DBUS_SESSION_BUS_ADDRESS and $XDG_RUNTIME_DIR not defined (consider using --machine=<user>@.host --user to connect to bus of other user)”
Both mean the shell has no XDG_RUNTIME_DIR, the variable that tells systemctl where the user manager listens. A login sets it; switching user does not, and pam_systemd says so: “$XDG_RUNTIME_DIR is not set if the current user is not the original user of the session.” Nothing is wrong with the service. Reach the account’s manager one of these ways:
- Log in as that user directly over SSH, which creates a real session.
- From an admin account, address the user’s manager, as the message suggests (the user name before
@, the local machine implied):
sudo systemctl --user -M alice@ status openclaw-gateway
sudo machinectl shell alice@ # a full login shell as aliceCopiedThe machinectl manual describes its shell as “in many ways similar to a su session, but, unlike su, completely isolates the new session from the originating session,” and inside it systemctl --user works as usual. On Debian and Ubuntu machinectl comes in the systemd-container package. Both need the user’s manager to be running, which on a server means lingering. OpenClaw’s gateway runbook gives a third route for a headless server: export XDG_RUNTIME_DIR=/run/user/$(id -u) before retrying.
When it is not the service at all
- A program started by hand dies when you log out, not one started by
systemctl --user: that is logind’sKillUserProcesses=, which ends everything in a login session at logout. The logind.conf manual gives its default as yes and warns it “will break tools like screen(1) and tmux(1)”; Ubuntu 24.04 ships it set to no. Lingering does not change it, because a user service runs under the user manager rather than in your session. - An agent session in tmux is gone after a reboot. tmux survives a disconnect, not a restart, as what tmux does and does not do explains; anything that must come back at boot needs a service.
- The service fails at boot with “cannot assign requested address” because it listens on the Tailscale IP before Tailscale has it; ordering it after Tailscale’s online target fixes that.
- The service starts and exits. Lingering is working; the program is failing.
systemctl --user statusshows the exit code andjournalctl --user -uthe reason, most often a binary not found becauseExecStarthad no full path.
Or a system service that runs as the user
The other way to start at boot is a unit in the machine’s own service manager with User=, which needs no lingering at all:
# /etc/systemd/system/agent-server.service
[Unit]
Description=Agent server
[Service]
User=alice
WorkingDirectory=/home/alice/agent
ExecStart=/home/alice/.local/bin/agent-server --port 8080
Restart=on-failure
[Install]
WantedBy=multi-user.targetCopiedsudo systemctl daemon-reload
sudo systemctl enable --now agent-server.service
journalctl -u agent-server.service -fCopiedLeave out User= and it runs as root, which OpenClaw’s runbook calls “unsafe and unsupported” for its gateway. %h here would be root’s home, hence the written-out paths. The trade-off is control: every start, stop and restart now needs sudo, which is why Nous’s page, for a headless machine you never log into, also offers the user service with lingering as the way to avoid root prompts. A user unit cannot do it the other way round: in a user service, User= can only name the account the manager already runs as.