Start with the log
Every start attempt writes a log line. Read it before changing anything — the error usually names the problem. If the agent is a service, the log is wherever your launch agent points; if you run it by hand, you already have the output.
The ordered checklist
- Login: run
remoteagent login— an expired session is the most common silent blocker. - Permissions: macOS asks for Full Disk Access and Automation the first time; a denied prompt blocks tools later, not just now.
- Gatekeeper: if the binary is quarantined, remove the flag or reinstall via the macOS install guide.
- Port conflicts: if the agent exposes a local endpoint, something else may hold the port.
- Reinstall as the last resort, keeping your config.
If it starts but tools fail
That is a different class of problem: permission denials are policy, not startup. A start that dies mid-run points to timeouts or memory.
Prevention on macOS
- Keep the agent updated — fixes land quietly.
- Test after every major macOS upgrade; permission prompts reset.
- If you run it as a headless service, monitor the log weekly, not after it has been down for days.