Agent Activation

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

1. 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.

2. Run the activate command

   On the machine where the agent is installed, run:

   grail-agent activate <PAIRING_CODE>

   You can optionally provide a name for the agent:

   grail-agent activate <PAIRING_CODE> "Office NAS Scanner"

   If no name is provided, the agent defaults to “Agent {hostname}”.

3. Start the agent

   Once activation succeeds, start the agent:

   grail-agent start

   You can verify the agent is running with:

   grail-agent status

4. Confirm in the web app

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

Tip

If the pairing code expires before you activate, close the modal and click Add Agent again to generate a new code.

Reactivating an Agent

If you need to move an agent to a new machine or recover from a corrupted configuration, you can reactivate it without losing its name, storage sources, or job history.

1. Generate a reactivation code

   In the Grail web app, go to the Agents page and click on the offline agent to open its settings. In the Reactivate Agent section, click Get Code. A 6-digit reactivation code will be displayed with a 10-minute countdown.

2. Run the reactivate command

   On the new machine (with the agent already installed), run:

   grail-agent reactivate <REACTIVATION_CODE>

   This replaces any existing configuration and issues new credentials for the same agent.

3. Start the agent

   grail-agent start

Note

Reactivation preserves the agent’s identity on the cloud side — its name, storage sources, and job history remain intact. Only the credentials are replaced.

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.