Skip to content

Application startup failures

The verified causes of AgentDock failing to start, and how to fix each one.

A handful of distinct problems can look like "AgentDock won't start." Work through these in order.

Native module ABI mismatch

AgentDock uses node-pty for terminal/PTY integration (Antigravity, and the raw terminal drawer). If it fails to load — commonly after an Electron or Node.js version change when building from source — rebuild the native module against your installed Electron version:

bash
npm run rebuild:native
npm run native:check

Missing execute permission on node-pty's spawn helper

node-pty's native spawn-helper binary can lose its execute bit during install on macOS or Linux. This normally fixes itself automatically (it runs on npm install via the postinstall script, and again before every macOS packaging build), but you can run it manually:

bash
node scripts/fix-native-permissions.js

It's not actually crashing — the OS is blocking it

Packaged builds are currently unsigned on both Windows and macOS. This isn't a crash — it's Gatekeeper or SmartScreen blocking an unsigned binary from launching:

  • macOS: "AgentDock can't be opened because it is from an unidentified developer." Right-click the app and choose Open, or allow it via System Settings → Privacy & Security → Open Anyway.
  • Windows: a SmartScreen warning dialog. Choose More info → Run anyway.

Linux sandbox errors

See Linux sandbox issues for the setuid_sandbox_host.cc fatal error specifically.

Related