Most recovery actions are available directly from Heartbeats. Open that page first if the app is still accessible — it gives the fastest path to logs, backend restart, and backup export.
The app will not open
If Agentic Studio fails to launch or shows a startup error:
- Quit Agentic Studio completely (
Cmd + Q or force quit from Activity Monitor)
- Reopen the app
- If it fails again, check whether macOS is blocking it — open System Settings → Privacy & Security and look for an Open Anyway prompt
- If there is no macOS block and the app still fails, continue to the logs section below
The app opens but the backend does not start
If the app window appears but the UI is not usable — blank state, spinner that never resolves, or an error about the backend:
- Open Heartbeats from the settings area in the sidebar
- Use Open Logs to open the logs folder in Finder
- Look for recent error messages in the log files
- Try Restart Backend — this stops and restarts the local backend process without losing any data
- If the error persists after restart, note the error message from the logs before taking further steps
An agent run fails with “command not found”
This usually means the runtime’s CLI tool is not on the PATH that Agentic Studio uses when launching processes.
- Confirm the CLI is installed: open Terminal and run the command directly (e.g.,
claude, codex, gemini)
- If it works in Terminal but not in Agentic Studio, the issue is PATH. macOS apps launched from the Dock or Finder do not inherit the shell PATH.
- Open Heartbeats → find the agent → check the CLI path or Runtime path field
- Set the full absolute path to the binary (e.g.,
/usr/local/bin/claude or /Users/you/.nvm/versions/node/v20.0.0/bin/node)
- Retry the run from Inbox
To find the full path in Terminal: which claude (replace claude with the runtime command).
An agent is not waking up on schedule
- Open Heartbeats
- Find the agent in the heartbeat table
- Check the Scheduler active column — if it shows inactive, the heartbeat is not running
- Check the Last heartbeat column — if it is stale by more than one interval, the agent missed its last cycle
- Try Restart Backend to reset the scheduler
Logs location
The logs folder is accessible from Heartbeats → Open Logs. The path on disk is:
~/.agenticstudio/instances/default/logs
Data and backup location
| Path | Contents |
|---|
~/.agenticstudio/instances/default/data | Local database and app state |
~/.agenticstudio/instances/default/data/backups | Exported backup archives |
Starting fresh
If local state is corrupted and recovery steps have not worked:
Reset Instance permanently deletes all local data — the database, run history, agent configuration, and logs. This cannot be undone. Export a backup first if there is any data worth preserving.
- Open Heartbeats
- Use Export Backup to save a copy of the current state
- Use Reset Instance
- Complete onboarding again from the beginning
After a reset, previously configured agents, issues, and projects are gone. The backup export can be used to manually inspect the old database if needed, but it is not automatically restored. 
