Agent Activation

After installing the agent, you need to activate it by pairing it with your Grail cloud account.

Generate a pairing code

In the Grail web app, navigate to Agents and click Add Agent. A 6-digit pairing code will be displayed along with a 10-minute countdown timer.

You can copy the code to your clipboard with the copy button.
Run the activate command

On the machine where the agent is installed, run:
Terminal window
```
grail-agent activate <PAIRING_CODE>
```
You can optionally provide a name for the agent:
Terminal window
```
grail-agent activate <PAIRING_CODE> "Office NAS Scanner"
```
If no name is provided, the agent defaults to “Agent {hostname}”.
Start the agent

Once activation succeeds, start the agent:
Terminal window
```
grail-agent start
```
You can verify the agent is running with:
Terminal window
```
grail-agent status
```
Confirm in the web app

The agent should now appear on the Agents page showing its status, hardware info, and capabilities.

Troubleshooting

Invalid or expired pairing code The code is valid for 10 minutes and can only be used once. Generate a new code in the web app.

Agent already activated If the agent was previously activated, run grail-agent status to check its current state. To re-activate with a different cloud account, uninstall and reinstall the agent:

grail-agent stop
grail-agent uninstall
grail-agent install
grail-agent activate <NEW_PAIRING_CODE>

Cannot connect to cloud API Ensure the machine has outbound internet access to vault.grailmedia.app.