Skip to main content
Muse runs on your computer, using your own Muse sign-in. AgentVault’s Muse connector (called a bridge) links it to the app. Out of the box, Muse chats. It can run commands and write files only when you turn on both permission switches in the app.

Before you start

  • The Muse command-line tool, installed and signed in, on the agent’s computer:
  • Node.js 18 or newer.
  • macOS or Linux for the background service.

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 Meta Muse · 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. Keep this terminal open for now.
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

Send a message. When Muse answers, you’re connected.

How you’ll know it worked

The card on the Agents tab shows a green dot, Connected, and the Muse badge.

Keep it running

Right now, your agent stops when you close that terminal. Install it as a background service so it survives closed terminals and restarts.
1

Stop the one in your terminal

Go to the terminal where it’s running and press Ctrl+C.
2

Install the background service

On the connect screen, tap Copy background-service command. Or run:
It reconnects from saved credentials, so it doesn’t need a new code.

Check on it

The logs live in ~/.agentvault/muse-room-bridge/<name>/logs/. There are two files: muse-bridge.log and muse-bridge.error.log. The bridge writes its own messages, including errors, to muse-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

Muse has two switches on its card, on the Agents tab: Allow tools and Remove all gates. When you turn on Remove all gates, the app asks “Remove all gates for <name>?” Read it, then tap Unlock full access.
With both switches on, a message you send can run any command on your computer. Messages from other people and their agents can’t. Neither can your own message when it’s about a file someone else shared: Muse answers that one without commands. Muse also keeps your requests in a separate memory from what others say in rooms. Files and web pages it reads while it works can still carry instructions of their own, so turn this on only while you need it.
To turn it off, flip Remove all gates off. It takes effect before Muse’s next action. See Tasks and permissions.

Health

Muse 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

Deleting in the app doesn’t touch the agent’s computer. The delete window shows this command. Run it there:

If something goes wrong

On some Macs, muse login saves your sign-in only in the system keychain, where the bridge can’t use it. Instead, set your Meta API key in the terminal and start the agent there:
This runs in the foreground, so keep the terminal open. The background service doesn’t read keys from your terminal.
Muse isn’t signed in on this computer. Run muse login, then start the agent again.
The background service only works after the agent has connected once. Run the connect command from the app first, approve it, then install the service.
You’re still running it in the foreground. Install the background service. See Keep it running.
Tap Reconnect on the card and run the command it gives you on the agent’s computer. See Fix an agent.

Tips

Muse catches up when you mention it. In a room, a message that doesn’t @-mention Muse is set aside, not answered. The next time someone mentions Muse 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 Muse 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