Skip to main content
Find your symptom below. Each section covers the most common cause and how to resolve it.

​
Connection issues

Claude requires a public HTTPS URL to reach your Reacher server.
  1. Confirm the server is running and reachable:
    You should get {"status":"ok",...}. If this fails, the problem is network/DNS, not Reacher.
  2. Verify your reverse proxy is forwarding to the correct port (default 3000).
  3. Make sure the full URL you gave Claude includes the token:
  4. Check that port 3000 is not blocked by a firewall on your VPS.
The MCP_SECRET in the URL does not match the one the server has loaded.
  1. Check what secret the server is using:
  2. Compare it to the token in the URL you registered in Claude.ai. They must match exactly — including case and any trailing whitespace.
  3. If you changed MCP_SECRET in .env, restart the container:
Check the container logs for the actual error:
Common causes:
  • Missing required env vars — MCP_SECRET, TAILSCALE_API_KEY, and GITHUB_TOKEN must all be set. A missing variable causes startup to fail with an explicit error message listing the missing keys.
  • Port already in use — another process is bound to port 3000. Change PORT in .env or stop the other process.
  • Malformed .env — quotes around values can cause parsing issues. Values in .env do not need quotes.

​
SSH issues

1

Check that the device is online

Ask Claude to run tailscale_status and confirm the target device shows as online: true. An offline device cannot be reached over SSH.
2

Verify Tailscale SSH is enabled on the target

Tailscale SSH must be explicitly enabled on each target machine. SSH to the device manually and run:
3

Test the connection manually

From the Reacher server itself, test that SSH works:
If this fails, the issue is with SSH credentials or Tailscale connectivity, not Reacher’s tool layer.
4

Check the SSH key

Reacher uses /root/.ssh/reacher-key. Verify it exists and is mounted correctly:
The key must have 600 permissions. Reacher sets this automatically, but verify if you mounted it manually.
The command matched an entry in SSH_BLOCKED_COMMANDS. The response includes matched_rule showing which rule triggered.To see your current blocklist:
If the block is incorrect — for example, a legitimate command contains a blocked substring — you have two options:
  1. Remove the specific entry from SSH_BLOCKED_COMMANDS or ssh.blocked_commands in your YAML config, then restart.
  2. Reword the command to avoid the substring. Remember that matching is substring-based, so dd if=... matches the blocked entry dd.
After changing the config, restart the server:
ssh_exec returned blocked: true with reason: "Path not in allowed directories".This means SSH_ALLOWED_DIRS (or ssh.allowed_dirs) is set and the command references a path outside the allowed prefixes.Options:
  1. Add the path to your SSH_ALLOWED_DIRS list:
  2. Clear the allowlist if you no longer want directory restrictions:
Restart the server after any change.

​
Tool errors

The target domain is not in PROXY_ALLOWED_DOMAINS.Add it to your .env:
Restart the server. The full hostname must match — api.github.com and github.com are treated as separate entries.
The GITHUB_TOKEN in your .env is either missing, expired, or lacks the required scopes.
  1. Verify the token is set:
  2. Check that the token has not expired in GitHub Settings → Tokens.
  3. Confirm the token has the right scopes:
    • repo (or specific repo access) for github_search and API calls via fetch_external
    • gist for gist_kb
  4. Generate a new token and update .env, then restart the container.
gist_kb requires GITHUB_TOKEN with gist scope (read and write). A token with only repo scope will fail.
  1. Go to GitHub Settings → Tokens
  2. Edit your token and enable the gist scope
  3. Save and update GITHUB_TOKEN in .env
  4. Restart the server
If the token was recently regenerated and you updated .env, confirm the container picked up the new value:

​
Browser tool issues

The browser tool depends on the agent-browser CLI being installed globally on the server.
If you’re running Reacher in Docker, this must be included in your Docker image or installed in the container. The default Dockerfile does not include it — add the install step if you need browser support:
Rebuild and restart the container after making this change.
The browser tool connects to a CDP-compatible browser at ws://BROWSER_CDP_HOST:BROWSER_CDP_PORT. Connection refused means no browser is listening on that address.
  1. Confirm the browser process is running.
  2. Check the default endpoint: ws://127.0.0.1:9222.
  3. If your browser is on a different host or port, update .env:
  4. Restart Reacher after changing the config.
Lightpanda is a lightweight headless browser with CDP support. To use it with Reacher:
  1. Download and install Lightpanda on your server following the instructions in its repository.
  2. Start Lightpanda with CDP enabled on port 9222:
  3. Leave BROWSER_CDP_HOST and BROWSER_CDP_PORT at their defaults, or set them to match your Lightpanda configuration.
  4. Verify the connection: