Troubleshooting & System Health
Diagnostic checks and common remediation steps for operating system permissions, container daemons, and display environments.
Integrated System Health Probe
In Kyro desktop settings, navigate to Diagnostics. Kyro executes an automated probe checking:
- • SQLite database connectivity and WAL mode activation.
- • Operating system keyring availability (or fallback status).
- • Docker and Podman daemon responsiveness.
- • Virtual display utilities (Xvfb status for Ghost Mode).
- • System CLI binaries (git, node, npm).
Common Scenarios & Fixes
Sandbox execution denied: "Container engine is unavailable"
Cause: Your shell governance policy is set to SandboxOnly, but Docker or Podman is not running.
Fix: Start Docker Desktop or start your local service:
sudo systemctl start docker
# or if using podman:
podman machine startmacOS: Screen Recording or Accessibility Permission Prompts
Cause: macOS requires explicit user grants in System Settings for applications that capture the screen or synthesize mouse and keyboard strokes.
Fix: Open System Settings → Privacy & Security, enable Kyro under both Screen Recording and Accessibility, and restart the application.
Linux: Keyring daemon DBus error on headless/minimal setups
Cause: In minimal window managers (i3, bspwm) without GNOME Keyring or KWallet, DBus secret service queries may time out.
Fix: Kyro automatically falls back to an authenticated AES-256-GCM encrypted database file with 0600 permissions located in ~/.config/kyro/vault.db. No manual intervention is required.
Reporting Unresolved Issues
If you encounter an unhandled exception or reproducible crash: