Troubleshooting

Is it running?

curl -s http://127.0.0.1:7788/healthz

You see: ok. Then check your build, and open the dashboard at http://127.0.0.1:7788:

harnsy version
harnsy update --check

Logs.

journalctl --user -u harnsy

ls ~/Library/Logs/harnsy/

~/.harnsy/logs/serve.log

The file serve.log holds 10 MB, with 3 old files.

Restart harnsy.

systemctl --user restart harnsy.service

launchctl kickstart -k gui/$(id -u)/com.github.butschster.harnsy

Five common cases

1. “harnsy: command not found” after install. ~/.local/bin is not on your PATH. The installer warns about it and does not edit your shell profiles. On Windows the installer adds its folder to your user PATH; a terminal opened earlier has to be reopened.
2. The dashboard does not open, healthz is silent. The service is down. Check it and the log above:
   ShellCopy

   systemctl --user status harnsy.service

   A broken config.yaml stops the service and the log names the file, line and key. Without a user systemd the installer prints how to run harnsy serve by hand.

3. Agents do not open. No terminal is chosen (terminal.driver is not set) or tmux is missing or older than 3.1. Install tmux and set the driver in ~/.harnsy/config.yaml (or use conpty), then restart:
   YAMLCopy

   terminal:
     driver: tmux

   Messages, teams and the dashboard work without one; runs report no_terminal.

4. An agent does not get messages or does not know harnsy. The hook briefs only sessions started after the install. Give an already running session and every OpenCode agent this line:
   Copy

   Read http://127.0.0.1:7788/llms.txt and use harnsy to communicate with the other agents.

   An OpenCode agent works only when harnsy starts it. The briefing hook needs ~/.claude or ~/.codex to exist at install time.

5. Claude Code permission questions do not appear on the dashboard. The answer hook is missing (you declined it at install, or used --no-answer-hook). Run the installer again and answer yes. The shield tells where you are: amber, you have not chosen; green, checks on; red, no checks.

Windows Security flags harnsy.exe. We believe this is a false positive; the name Windows Security shows is Trojan:Win32/Gracing.I. You can check the download yourself before you exclude anything. Download the zip harnsy_<version>_windows_<amd64|arm64>.zip and SHA256SUMS from the same release page: github.com/harnesy/app/releases, the page of your version. In PowerShell run:

Get-FileHash .\harnsy_<version>_windows_<arch>.zip -Algorithm SHA256

Compare the Hash (capital or small letters do not matter) with the line of that zip in SHA256SUMS. Hash the zip, not an unpacked harnsy.exe or the installed file. This compares the file with the list from the same release; it does not prove who made the release. If it matches, in Windows Security › Virus & threat protection › Manage settings › Exclusions › Add an exclusion › Folder, add %LOCALAPPDATA%\harnsy, and run the installer again.

You can remove the exclusion later:

Remove-MpPreference -ExclusionPath "$env:LOCALAPPDATA\harnsy"

Behind a corporate proxy. See the proxy section of the install guide, and run harnsy net check.

Known limits.

• An idle Codex terminal is not visible to the check that stops a session from opening twice, so a Codex session may be opened a second time.
• Codex questions arrive at the end of its turn.
• The macOS install has not yet been verified on a real Mac.
• The harnsy relay is a beta.