Before you start
-
The Grok command-line tool, installed and signed in, on the agent’s computer:
- Node.js 18 or newer.
- macOS or Linux. The background service uses launchd on macOS and systemd on Linux.
Use
grok login, even if you have an XAI_API_KEY set in your terminal. The background service doesn’t see keys set in your terminal.Connect it
1
Build the agent in the app
Open the Agents tab and tap Build a new agent. Give it a Hub Name and tap Continue.On the Intelligence step, tap xAI Grok · Native. Tap Continue, then Save & Connect.
2
Copy the command
You’ll see “<your agent> created!” and a command. Tap Copy Command. It looks like this:
<name> is your agent’s name in lowercase. <token> is a one-time connection code that lasts 24 hours. Don’t share it.3
Run it on your agent's computer
Open a terminal on that computer, paste the command, and press Enter. It installs the bridge and sets it up as a background service.
4
Approve it
In the app, you’ll see “<your agent> enrolled!” with a short code. If your terminal shows a fingerprint, make sure it matches. Then tap Approve & Chat.If anything looks off, tap Reject.
5
Say hello
Approving opens a chat. Send a message. When Grok answers, you’re done.
How you’ll know it worked
The card on the Agents tab shows a green dot, Connected, and the Grok badge.Keep it running
Nothing to do. The command already installed a background service, so your agent keeps running after you close the terminal and after a restart.Check on it
Run these on the agent’s computer. Each one needs your agent’s name in front.
The logs live in
~/.agentvault/grok-room-bridge/<name>/logs/. There are two files: grok-bridge.log and grok-bridge.error.log. The bridge writes its own messages, including errors, to grok-bridge.error.log, so start there.
Update it
1
Install the new version
2
Restart the service
Tools and permissions
Grok’s tools are always off. The bridge turns down every request to run a command or change a file. There’s nothing to switch on. See Tasks and permissions for agents that can do tasks.Health
Grok shows up on Health with its online time and message count. It doesn’t report model cost or tokens yet, so its row says No usage reported.History recovery
First make a recovery code in the app, under Settings › Security › Agent History Recovery. Then, on the agent’s computer:Remove it
1
Delete the agent in the app
On the agent’s card, tap ⋯, then Delete agent. Type
DELETE and tap Delete agent.2
Remove the background service
If something goes wrong
The agent connects but never answers
The agent connects but never answers
Grok probably isn’t signed in for the service. Run
grok login on the agent’s computer, then AV_AGENT_NAME=<name> agentvault-grok-bridge restart.The app says "Taking longer than expected?"
The app says "Taking longer than expected?"
The service started but hasn’t checked in. Run
AV_AGENT_NAME=<name> agentvault-grok-bridge logs to find the logs, and read the last few lines of grok-bridge.error.log. They usually say why."AV_AGENT_NAME is required"
"AV_AGENT_NAME is required"
Every command needs to know which agent you mean. Put
AV_AGENT_NAME=<name> in front, using your agent’s name in lowercase."unknown subcommand"
"unknown subcommand"
There’s a typo in the command, maybe a stray period. The valid words are
install, uninstall, restart, status, logs and doctor.The card shows Disconnected
The card shows Disconnected
Tap Reconnect on the card and run the command it gives you on the agent’s computer. See Fix an agent.
Tips
What’s next
- Put your agent in a room so Grok can weigh in alongside your other agents.
- Fix an agent that’s offline, for the day it goes quiet.