Source: https://harnsy.dev/docs/troubleshooting

> Something does not work. Start with the checks, then find your case.

# Troubleshooting

Something does not work. Start with the checks, then find your case.

## Is it running?

Shell

```bash
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`:

Shell

```bash
harnsy version
harnsy update --check
```

> Note
> 
> There is no `harnsy doctor`. These commands help: `harnsy config` (your settings and where each comes from), `harnsy net check` (can this computer reach the services it needs, through your proxy), `harnsy license` (the state of your key). The Settings page “Diagnostics” collects data for a time you choose; the archive is built to hold no keys or tokens; open it and look through it before you send it.

**Logs.**

**Linux**

```bash
journalctl --user -u harnsy
```

**macOS**

```bash
ls ~/Library/Logs/harnsy/
```

**Windows and anywhere else**

```bash
~/.harnsy/logs/serve.log
```

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

**Restart harnsy.**

**Linux**

```bash
systemctl --user restart harnsy.service
```

**macOS**

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

> Note
> 
> During the restart a send fails for a few seconds: run it again.

## 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:
   Shell
   
   ```bash
   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:
   YAML
   
   ```yaml
   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:
   ```text
   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](https://github.com/harnesy/app/releases), the page of your version. In PowerShell run:

PowerShell

```powershell
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.

> Warning
> 
> Never turn Defender off, and never exclude `%TEMP%` or a whole drive.

You can remove the exclusion later:

PowerShell

```powershell
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.

Since harnsy 0.1.

Anthropic, Claude Code, OpenAI, ChatGPT, Codex, OpenCode, Telegram, Discord, GitHub, Apple, macOS, iOS, iPhone, Safari, Google, Android, Chrome, Microsoft, Windows, Windows Security, Defender and QR Code are names of their owners’ products. harnsy is not affiliated with or endorsed by them. iOS is a trademark of Cisco used under licence by Apple; QR Code is a registered trademark of DENSO WAVE INCORPORATED. No logos.