Docs

Troubleshooting

An AI tool shows Silent, a laptop isn't reporting, a block didn't hold, Codex needs approval. What each means and what to do.

An endpoint page: the Sensor panel says what it can and cannot see.

An AI tool shows Silent

ZYBE is connected to it, the tool has been running, and ZYBE hasn't heard from it. Almost always the tool was open when ZYBE was installed. Restart the tool.

If it stays Silent after a restart, check the laptop's Detections for lost its connection to ZYBE: the sensor restores a removed registration within a minute and says so there. To check the hook by hand on the laptop:

printf '{"session_id":"check","tool_name":"Read","tool_input":{"file_path":"/tmp/x"}}' | /usr/local/zybe/bin/zybe-hook; echo "exit $?"

should print exit 0. If not, read /var/log/zybe/sensor.log.

Codex shows Blocking but says approval is pending

On a just-me install, Codex won't run ZYBE until the developer approves it once. Open Codex, type /hooks, approve zybe-hook. A whole-machine install doesn't need this.

A block didn't hold

Check in this order.

  1. The tool's state on that laptop. Open the laptop, click Sensor. Only a tool that shows Blocking can refuse anything.
  2. Pause all enforcement, under Rules, Advanced. If it's on, every Block is a Report.
  3. Which profile governs this laptop and this tool. Profiles are first match wins. A profile scoped to other AI tools doesn't apply to this one.
  4. An exception. The Requests page lists exceptions granted on this laptop.

A laptop isn't reporting

On the laptop: Mac, sudo launchctl print system/ai.zybe.sensor. Linux, systemctl status zybe-sensor.timer. Windows, the scheduled task "Zybe Sensor". ZYBE's log is in /var/log/zybe or ~/.zybe/log. The console raises Endpoint has stopped reporting by itself after two missed scans.

Full Disk Access on Mac

Some AI tools keep files where macOS protects them. The installer warns if the terminal lacks Full Disk Access. System Settings, Privacy & Security, Full Disk Access, switch on Terminal, run the installer again. The console shows what it couldn't read as a blind spot, never as clean.

An update failed

The laptop refuses an update that doesn't check out and keeps running what it has. The reason is in update.log next to the other logs, and on the laptop's page in the console.

Uninstall by hand

sudo /usr/local/zybe/bin/uninstall-macos.sh     # Mac
sudo /opt/zybe/bin/uninstall-linux.sh           # Linux

The uninstaller disconnects ZYBE from every AI tool, puts their settings back, and checks that nothing is left.