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

If the agent appears to stall during startup, update to the latest release and reinstall the service helpers:

grail-agent update
grail-agent install

Recent releases prevent common startup stalls caused by slow tunnel sign-in or an unresponsive SMB watcher startup.

Storage Source Shows Offline or Degraded

Open Storage Sources in the web app and check the storage source card:

Mount Failed means the agent cannot reach the SMB share or base path.
Disconnected under detection means real-time watching is not currently connected. For Watch + Poll sources, scheduled polling continues as a fallback.
Polling means the source is intentionally using scheduled scans instead of real-time watching.

If the card shows a mount error, verify the SMB host, share, base path, and credentials. After fixing the configuration, click Start Scan to retry indexing. On macOS, updating to the latest agent can also help when the share is already mounted at a numbered path such as /Volumes/share-1.

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 Docker is running but SMB watcher containers still cannot reach your NAS or other LAN hosts, the Colima VM subnet may overlap with your local network. Current Grail agent releases automatically detect and correct this conflict. If you are still seeing connectivity issues, update the agent and restart Colima:

grail-agent update
grail-agent install
colima restart

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.

Endpoint Security Software Blocking the Agent

Endpoint detection and response (EDR) software such as SentinelOne, CrowdStrike, or Carbon Black may flag the Grail agent binary as a threat and quarantine or delete it. This is a false positive — the agent is a signed and notarized macOS application.

To resolve this, ask your security team to add a certificate-based exclusion for the Grail agent:

Field	Value
Signer Identity	`Developer ID Application: App Press LLC (VUNENW3JSP)`
Team Identifier	`VUNENW3JSP`

SentinelOne

Open the SentinelOne management console.
Navigate to Sentinels → Exclusions → New Exclusion.
Set the exclusion type to Signing Certificate.
Enter the Team Identifier: VUNENW3JSP
Set the appropriate scope (site or group).

Other EDR Products

For other endpoint security products, create a code signing certificate exclusion using the signer identity or Team Identifier listed above. Refer to your EDR vendor’s documentation for the specific steps.

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.

If the agent’s tunnel is temporarily unavailable, Grail queues the restart request and delivers it when the agent reconnects.

Verify it’s running again:

grail-agent status