Skip to content
Open Conduit

Run it in the background

service install runs the daemon as a per-user service: a launchd LaunchAgent on macOS, a systemd user unit on Linux. It starts at login, restarts if the daemon exits with an error, and runs in your session, so the OS keyring and your gh and Claude Code logins work as they do in a terminal.

Terminal window
open-conduit service install                         # takes serve's flags
open-conduit service status
open-conduit service stop                            # until the next start or login
open-conduit service start
open-conduit service uninstall
  • install records the config path, the state directory, the serve flags you give it and a PATH built from your shell’s PATH and wherever claude or codex, git and gh are. It warns when it can’t find git, or neither claude nor codex. A tunnel’s program (ngrok, cloudflared) is found on your shell’s PATH, or at the tunnel config’s binary. Its package’s doctor check reports when it is missing.
  • start (and install, which starts the service) returns once the daemon answers on its socket, waiting up to 30 seconds. launchd holds a start back for 10 seconds after the daemon last exited, so a start straight after a stop takes a little longer; once that has passed, start asks launchd again. A daemon that doesn’t come up in time is reported as an error with the log’s path, never as started.
  • Run install again after changing flags or installing a tool the daemon needs (a repository’s toolchain, say): it replaces the unit and restarts the daemon.
  • open-conduit upgrade, or the web view’s Update page, installs a new release and restarts the service on it (see upgrading).
  • A brew upgrade restarts the daemon on the new version too. When the files the daemon runs from are removed, as brew upgrade does with the old version’s directory, it stops with an error, and the service starts the new binary. Running turns carry on and the new daemon adopts them, but a shell step that calls os after the upgrade fails, since its PATH still names the removed directory. Upgrading while open-conduit doctor shows nothing running under capacity avoids that.
  • Remove the service with service uninstall before a plain brew uninstall, or use brew uninstall --zap open-conduit, which removes it with the cask. If the cask is already gone, launchctl bootout gui/$(id -u)/com.open-conduit.daemon and deleting the plist clear it.
  • Webhooks come from the config’s settings.webhooks, as with serve.
  • Output goes to ~/.local/state/open-conduit/logs/service.log (under --data-dir if you give one). open-conduit doctor reports whether the service is installed and running.
  • The unit lives at ~/Library/LaunchAgents/com.open-conduit.daemon.plist or ~/.config/systemd/user/open-conduit.service.
  • Stop the service before backup create or state check, which need the daemon stopped.