Agent Troubleshooting

Agent Commands

The grail-agent CLI provides commands for managing the agent service:

# Check agent activation and service status
grail-agent status

# Check the installed version
grail-agent version

# Start the agent service
grail-agent start

# Stop the agent service
grail-agent stop

# Restart the agent service (stop + start)
grail-agent restart

# Update to the latest version (beta 8+)
grail-agent update

# Tail the agent log (Ctrl+C to stop)
grail-agent logs

# Tail the error log
grail-agent logs --error

Log files are stored at:

Main log: ~/.grail-agent/grail-agent.log
Error log: ~/.grail-agent/grail-agent.error.log

Agent Won’t Start

Check if the service is installed:

grail-agent status

If the status says “Service is not installed”, run the installer:

grail-agent install

Check the error log for details:

grail-agent logs --error

Agent Not Appearing in Web App

Verify the agent is running:
Terminal window
```
grail-agent status
```
Check that the agent is activated:

If the status shows “Not activated”, you need to activate the agent first.
Check the logs for connection errors:
Terminal window
```
grail-agent logs
```
Look for errors connecting to vault.grailmedia.app. Ensure the machine has outbound internet access.

Docker or Colima Not Running

The agent automatically starts Colima if it detects Docker is not running on macOS. If Colima is not installed, the agent installs it via Homebrew (along with Docker and docker-compose) and registers it as a brew service for auto-start on login.

If auto-remediation fails, check the agent logs for details and try manually:

colima start
brew services start colima

If colima start fails with “error starting vm: exit status 1”, delete the existing instance and retry:

colima delete
colima start

SMB Shares Won’t Mount

If the agent cannot mount SMB/network shares and you see authentication or mount errors in the logs, macOS’s NetAuthSysAgent process may be in a bad state.

Fix:

killall NetAuthSysAgent

This forces macOS to restart its network authentication system. The agent will retry mounting shares automatically on its next scan cycle.

Agent Out of Date

If the agent is behaving unexpectedly, check the version and update:

grail-agent version
grail-agent update
grail-agent install

Restarting the Agent

If the agent is misbehaving, a restart often resolves transient issues:

grail-agent restart

You can also restart an agent from the web app by opening the Edit Agent modal and clicking Restart.

Verify it’s running again:

grail-agent status