Running the device server as a service
Run ch device-server as a background service with systemd or launchd, so it survives logout and reboot.
Running ch device-server in a terminal works for a quick test, but the device goes Offline as soon as that terminal closes. Set it up as a background service instead. The device server then starts at login, restarts after a crash and survives reboots, so agents can always pick up work. If you’d rather the device clean up and take itself out of the fleet once it runs out of work, see Devices that clean up after themselves instead.
Before you start
One thing must be in place before you set up the service: a CLI credential. For an unattended service, use either CH_TOKEN (an API key) or a named profile. Mint an API key from Admin → People → Members or with ch member keys create — see Minting API keys. See Credentials and profiles for how to store it in a profile.
Register the device interactively once, before installing the service. Run ch device-server yourself from a terminal first and accept the one-time registration prompt — see How do I add a device? for what that prompt looks like and what it does. If you install the service first, it starts and keeps running. With no terminal to answer the prompt, it never registers, so the device never appears in your workspace. The service writes one line to its log that says so (see Confirm the device is Online), and then it idles. Once ch device list confirms the device is Online, the service setup below can take over — every subsequent start just reads the saved token and reconnects, prompt-free. See Quickstart for the full walkthrough from a fresh account.
A ch start registration counts too. If you’ve already run ch start on this machine, it registered a device — as a personal one, disabled by default (see Personal devices). Installing the service on that same registration brings it Online, but the engine still won’t hand it other people’s tasks until you promote it:
ch device enable <deviceId>
What the device server needs at startup
ch device-server requires three things before it can connect:
1. A CLI credential — the credential the device server uses to talk to CodeHerder. Supply it with the CH_TOKEN environment variable, or with CH_PROFILE set to the name of a credential profile.
2. A server address. Some ch builds already know which server to use. If yours does not (for example, a self-hosted setup), set CH_ADDR to your server’s URL in the service file, or put CH_ADDR in the profile file. See Credentials and profiles.
The server checks the credential, the address and the profile at start. It stops if one check fails:
- If the credential or the address is missing, the server prints “no CLI auth configured”. A
config error:line follows and names what is missing. - If
CH_PROFILEnames a profile that cannot load, the server printsch device-server: profile "<name>": …with the reason, for example a missing file.
In both cases the exit code is not zero, so the service manager keeps restarting it.
3. The device token file — ~/.codeherder/device.token by default. This file is written the first time you run ch device-server interactively and accept the registration prompt (see How do I add a device?) — a non-interactive run never writes it, which is why registering first, before installing the service, matters (see above). The server must run as the user who owns this file so the ~ path resolves correctly. If you need to run the server as a different user, pass --token-file <absolute-path> to point at the file explicitly. See Device tokens for what this token is and how to rotate it if it’s ever compromised.
Linux: systemd user service
A systemd user service runs as your account, starts at login, and automatically restarts the server if it exits unexpectedly.
1. Create the unit file
mkdir -p ~/.config/systemd/user
Write the following to ~/.config/systemd/user/codeherder-device-server.service. Replace the ExecStart path with the location of your ch binary (run which ch to find it) and fill in your credentials:
[Unit]
Description=CodeHerder device server
After=network-online.target
Wants=network-online.target
[Service]
ExecStart=%h/.local/bin/ch device-server
Restart=on-failure
RestartSec=5
Environment="CH_TOKEN=<your-api-key>"
[Install]
WantedBy=default.target
%h is a systemd specifier that expands to your home directory. Adjust the binary path if you installed ch elsewhere.
If your ch build has no built-in server address, add a second line under [Service]:
Environment="CH_ADDR=https://codeherder.example.com"
Using a credential profile instead: To keep credentials out of the unit file, create a profile at
~/.codeherder/main.env(see Credentials and profiles) and replace theCH_TOKENline above with:Environment="CH_PROFILE=main"A profile can also hold
CH_ADDR, so you do not need the extra line.
2. Enable and start the service
systemctl --user daemon-reload
systemctl --user enable --now codeherder-device-server.service
enable registers the service for future logins; --now starts it immediately.
3. Start at boot (not just at login)
By default, user services start only when you log in interactively. To start the device server at boot — before any login — enable lingering for your account:
loginctl enable-linger $USER
This keeps your user session alive at boot so your user services start as soon as the machine is ready.
Useful commands
# Check service status
systemctl --user status codeherder-device-server
# Follow live logs
journalctl --user -u codeherder-device-server -f
# Restart after a configuration change
systemctl --user restart codeherder-device-server
# Stop the service
systemctl --user stop codeherder-device-server
macOS: launchd LaunchAgent
A launchd LaunchAgent runs as your account, starts at login, and automatically restarts the server if it exits.
1. Create the plist
Write the following to ~/Library/LaunchAgents/com.codeherder.device-server.plist. Replace the binary path with the absolute path to your ch binary (run which ch to find it) and fill in your credentials:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.codeherder.device-server</string>
<key>ProgramArguments</key>
<array>
<string>/Users/youruser/.local/bin/ch</string>
<string>device-server</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>CH_TOKEN</key>
<string>your-api-key</string>
</dict>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/tmp/codeherder-device-server.log</string>
<key>StandardErrorPath</key>
<string>/tmp/codeherder-device-server.log</string>
</dict>
</plist>
RunAtLoad starts the server as soon as the plist is loaded (and at every subsequent login). KeepAlive restarts it automatically if it exits.
Using a credential profile instead: Replace the
CH_TOKENentry inEnvironmentVariableswith aCH_PROFILEentry pointing to your named profile:<key>CH_PROFILE</key> <string>main</string>The profile file at
~/.codeherder/main.envis read at startup. See Credentials and profiles.
If your ch build has no built-in server address, add a CH_ADDR entry to the same EnvironmentVariables dict (or put CH_ADDR in the profile file):
<key>CH_ADDR</key>
<string>https://codeherder.example.com</string>
2. Load the agent
launchctl load ~/Library/LaunchAgents/com.codeherder.device-server.plist
The agent starts immediately and loads at every subsequent login.
Useful commands
# Stop and unload the agent
launchctl unload ~/Library/LaunchAgents/com.codeherder.device-server.plist
# Reload after editing the plist
launchctl unload ~/Library/LaunchAgents/com.codeherder.device-server.plist
launchctl load ~/Library/LaunchAgents/com.codeherder.device-server.plist
# Follow live logs
tail -f /tmp/codeherder-device-server.log
Per-stage containers under a service manager
To run each stage in its own container, set CH_ISOLATION=isolated. Docker must be installed and running on the device. See Agent isolation for the options and what each one protects. Under systemd:
Environment="CH_ISOLATION=isolated"
Under launchd, add this to the EnvironmentVariables dict:
<key>CH_ISOLATION</key>
<string>isolated</string>
Auto-update under a service manager
When a release source is configured, ch device-server checks for a newer ch release about once an hour and installs it by itself. See Updating the CLI for how updates work, the flags, and the option that stops running agents during an update.
Two facts matter under a service manager:
- The server replaces itself in place instead of exiting. systemd and launchd see no restart, and they keep supervising the same process.
- By default, running agent sessions carry across the update without interruption.
To change auto-update behaviour, set these environment variables in your service file:
| Variable | Effect |
|---|---|
CH_DS_AUTO_UPDATE=0 |
Disable automatic updates. |
CH_DS_AUTO_UPDATE_INTERVAL=6h |
Check every six hours instead of every hour. |
Tuning session capacity and storage
By default, the device server stores session worktrees in ~/codeherder-sessions and caps the total at 8 simultaneous worktrees. Three settings let you tune this on a self-managed device server. Each has a flag and an environment variable:
| Flag | Environment variable | Default | What it controls |
|---|---|---|---|
--session-root <abs-dir> |
CH_SESSION_ROOT |
~/codeherder-sessions |
Parent directory for per-session git worktrees. Use an absolute path. The Session root readiness check fails for a relative path. The Session root and Disk headroom checks (visible in Managing your devices) report on this filesystem. |
--max-session-worktrees <n> |
CH_MAX_SESSION_WORKTREES |
8 |
Device-local cap on simultaneous session worktrees. The device runs at most the smallest of this value, its Session limit (set in the web app), and the platform-wide ceiling. Raise this only after you raise the server-side limits and want more parallelism on a bigger machine. The Session capacity readiness check reports how close the device is to this cap. |
--session-disk-budget-mb <mb> |
CH_SESSION_DISK_BUDGET_MB |
0 (count cap only) |
Optional cap on total session-worktree disk in MB. At 0, only the worktree-count cap applies. When set, Session capacity also reports disk usage against this budget. |
Every setting resolves the same way: the flag wins, then the environment variable, then the default. An environment variable is handy in a service file, where adding an entry is easier than editing the command line.
See Managing your devices for how the per-device limit and platform-wide ceiling combine to set the running-session cap.
For the other directories that grow on a device, how to measure them, and the disk alert level, see Self-hosted device disk growth.
Applying these flags under a service manager
Linux (systemd) — append the flags to the ExecStart= line:
ExecStart=%h/.local/bin/ch device-server --session-root /data/codeherder-sessions --max-session-worktrees 4
Reload and restart the service after editing the unit file:
systemctl --user daemon-reload
systemctl --user restart codeherder-device-server
macOS (launchd) — add each flag as a separate <string> entry in the ProgramArguments array:
<key>ProgramArguments</key>
<array>
<string>/Users/youruser/.local/bin/ch</string>
<string>device-server</string>
<string>--session-root</string>
<string>/Users/youruser/codeherder-sessions</string>
<string>--max-session-worktrees</string>
<string>4</string>
</array>
Reload the plist after saving:
launchctl unload ~/Library/LaunchAgents/com.codeherder.device-server.plist
launchctl load ~/Library/LaunchAgents/com.codeherder.device-server.plist
To apply an environment variable under a service manager, add it to the environment block, as in the Linux: systemd and macOS: launchd sections above.
Confirm the device is Online
After the service starts, check that the device is connected:
ch device list
The device should show Online within a few seconds. If it doesn’t, the symptom tells you which problem you have:
- The service keeps restarting, or the process won’t stay up. This is the startup check: no
CH_TOKENis set,CH_PROFILEdoesn’t name a profile it can load, or no server address resolves, so the server exits every time it starts. If the credential or the address is missing, the log shows “no CLI auth configured” and aconfig error:line. If the profile cannot load, the log showsch device-server: profile "<name>": …instead. Fix the unit file or plist, then restart the service. (ACH_TOKENthat’s set but wrong or revoked passes this check — the server starts and only fails later, once it tries to actually talk to CodeHerder.) - The service stays running, but the device never shows up in
ch device list. The device token file was never written. The service started before you registered interactively, so it has nothing to connect with and idles. Its log has the linech device-server: no device token at <path>. Find it withjournalctl --user -u codeherder-device-serveron Linux, or in/tmp/codeherder-device-server.logon macOS. Register the device from a terminal first (see How do I add a device? and the prerequisite above), confirm it’s Online, then restart the service so it picks up the saved token. - The service runs and the device shows Online, but no work ever lands on it. This is a personal device, most likely one
ch startregistered on this machine earlier. Promote it withch device enable <deviceId>— see Personal devices.
See the Troubleshooting section of Managing your devices for more on these cases.
Related guides
- How do I add a device? — the focused first-run steps to connect a machine
- Managing your devices — day-to-day device health, capacity, and troubleshooting
- Monitoring your agents — watch fleet health once the service is running
- Updating the CLI — how the service keeps its own binary current
Last updated