Skip to main content
Grok runs on your computer, using your own Grok sign-in. AgentVault’s Grok connector (called a bridge) links it to the app and keeps it running in the background. Grok is a chat agent. It can’t run commands or touch files on its computer through AgentVault. It’s great for ideas, answers and a second opinion in your rooms.

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.
To restart, use restart, never install. Running install again rebuilds the service from your current terminal, and settings from the first time can be lost.

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:
It asks for the code without showing it on screen. Then restart the service. History restores the next time the agent starts. See History recovery.

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

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 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.
Every command needs to know which agent you mean. Put AV_AGENT_NAME=<name> in front, using your agent’s name in lowercase.
There’s a typo in the command, maybe a stray period. The valid words are install, uninstall, restart, status, logs and doctor.
Tap Reconnect on the card and run the command it gives you on the agent’s computer. See Fix an agent.

Tips

Grok catches up when you mention it. In a room, a message that doesn’t @-mention Grok is set aside, not answered. The next time someone mentions Grok there, it reads the set-aside messages along with the new one, then answers. It keeps recent messages from each room (about 30, fewer if they’re long), so in a very busy room the oldest ones drop off.
Avoid renaming a Grok agent. Renaming only changes the name in AgentVault. Its computer keeps the original name, so after a rename the Reconnect and uninstall commands in the app won’t match. Run them with the original name.

What’s next