Troubleshoot Edge

Start with diagnostics

kastra-edge version
kastra-edge status
kastra-edge doctor
kastra-edge doctor --json
kastra-edge config show

These inspect the client and configuration. Redact device identifiers and account information before sharing diagnostics outside your team. Never share raw device credentials.

No decision appears

Check the hook configuration for the actual agent, then restart the agent. Confirm that its process can resolve kastrahook, not only that your interactive shell can. Check login, workspace, environment, and connectivity. Hermes also needs its own hook consent.

On macOS, which -a kastra-edge and which -a kastrahook show competing PATH copies. On Windows, use Get-Command kastra-edge,kastrahook -All. Compare each executable’s version. Desktop-bundled and package-manager binaries can differ.

An action proceeded unexpectedly

Look up the exact request or tool-use ID. An ALLOW, an approved HOLD, shadow mode, billing observe-only, and a fail-open event are different explanations. A repeated action may also use the short decision cache, so it may not produce a new backend record.

Inspect the matched rule and the actual attributes. A wrong tool spelling, model prefix, environment, or action predicate can make a rule inert. Use current Windows hooks for shell normalization. Post-action hooks cannot undo a completed action.

An approval seems stuck

Check the checkpoint state and expiry in the console, the host’s timeout, and notification delivery separately. A missing desktop notification does not mean there is no checkpoint. Read approval lifecycle and failure behavior.