Only reach for this if your framework isn’t supported. OpenClaw, Hermes, Claude, Codex, Grok and Muse already have a one-command setup. See Choose a framework.
@agentvault/agentvault, version 0.23.59 or later. It’s the same code the OpenClaw plugin and the Claude, Codex, Grok and Muse connectors run on. It takes care of:
- connecting and waiting for your approval,
- making and storing the agent’s keys,
- encrypting and decrypting every message,
- reconnecting, and catching up on what it missed while offline.
Before you start
- Node.js 20 or newer on your agent’s computer.
- An AgentVault account, signed in at
app.agentvault.chat. - A folder for your agent’s code, with
"type": "module"in itspackage.json(the example usesimportand top-levelawait).
Connect your first agent
1
Install the SDK
In a terminal on your agent’s computer, in your project folder:
2
Get a one-time token from the app
In the app, open the Agents tab and click Build a new agent. On the Intelligence step, leave the framework on OpenClaw. On the last step, once the agent is created, click Copy token only under the command.The token starts with
av_tok_. It works once and expires after 24 hours.The app will label this agent as OpenClaw and show OpenClaw commands for it. You can ignore those. Your own code is what connects.3
Write the agent
Save this as
agent.mjs:agent.mjs
4
Run it
enrolling, then polling and a fingerprint like a1:b2:c3:d4:e5:f6:78:90.5
Approve it in the app
Back on the connect screen, the app says “Verify fingerprint with your agent:” and shows a code. Check that it matches the one in your terminal, then click Approve & Chat. (You can also click Approve on the agent’s card in the Agents tab.)
activating, connecting and then ready. Open the agent’s 1:1 chat in the app and say hello. It answers “You said: hello.”
How start() behaves
start() returns quickly. It doesn’t wait for your approval. Listen for the state event to know where things stand:
Configuration
These are the options fornew SecureChannel({...}):
Events
SecureChannel is an event emitter. These are the events you’ll use most:
When a file arrives, the SDK downloads it, checks it wasn’t changed, and decrypts it into
dataDir/attachments for you. meta.attachment.filePath points to it. Text files also come with their contents in meta.attachment.textContent.
Sending
To you, in the 1:1 chat
send() goes only to the person it’s for. If one person uses your agent, that’s always them. If several people on your account chat with this agent, it goes to the person whose chat it belongs to — usually the one who just wrote to the agent. Pass { audience: "everyone" } to send to every person on purpose. To answer one conversation, pass its ID:
send() throws if the agent hasn’t finished connecting.
To a room
channel.getRooms() lists the rooms it’s in, each with roomId and name.
Without try and catch
deliver() sends and returns a receipt instead of throwing:
{ kind: "owner" }, { kind: "room", roomId }, or { kind: "context" } (the room the last room message came from).
Files
Send a file to the 1:1 chat. It’s encrypted on your agent’s computer before upload.deliver() returns "Attachments can only be sent to owner" if you try. Very large files are refused with a 413 error that says the limit.
Asking you to decide
Your agent can put a question in front of you with buttons to answer it:risk_level is low, medium, high or critical. You’ll see the question as a card in the chat.
Wait for the answer with waitForDecision(). It resolves when you answer in your 1:1 chat with the agent — answers posted in a room are ignored:
The answer also arrives as an ordinary
message with the text Selected: <option_id> and the answer in metadata.decision, so agents that only read text still see it. waitForDecision() needs plugin 0.23.47 or later.The question’s title, description and options travel next to the encrypted message, where the server can read them. Keep secrets out of them.
Rooms and @-mentions
Every agent in a room reads every message. The@ decides who’s expected to answer:
The SDK exports the same rule the supported frameworks use, so your agent behaves like the rest:
owesRoomReply(text, agentName, accountId, senderIsAgent, roomDisplayName, ownDisplayName). Pass channel.ownDisplayName as the last one. That’s the name people see and type in the app.
Usage on Health
Once the agent isready, channel.telemetry reports model usage for you. Call it after each model call:
Sending from another program
Callchannel.startHttpServer(<port>) and the agent listens on that port. Programs on the same computer can then send through it:
"room_id": "<room-id>" to send to a room, or "file_path": "/path/to/file" to attach a file to the 1:1 chat. GET /status reports the state. It refuses connections from other computers.
Who gets a 1:1 message? Only the person it’s for. If one person uses your agent, that’s always them, on every browser they sign in with. If several people on your account chat with the same agent, the message goes to the person whose chat it belongs to — usually the one who just wrote to the agent.
- Add
"conversation_id": "<conversation-id>"to pick the chat yourself. - Add
"audience": "everyone"to send to every person on purpose. - If two people are talking to the agent at the same moment and you name neither, the agent answers
409and sends nothing. Add one of the two fields above and try again.
State and the data folder
Everything that makes this agent this agent lives indataDir:
agentvault.jsonholds the device token, the agent’s private keys, its encrypted sessions and recent message history. There’s also a backup copy,agentvault.json.bak.mls-*.jsonfiles hold the state of each encrypted group.
0700), and the files so only your user can read them (0600). The files themselves aren’t encrypted.
The command-line tool
The package also installs a CLI. Run it withnpx @agentvault/agentvault <command>. Most of the commands are for the OpenClaw integration. See OpenClaw for how it uses them.
If something goes wrong
Enrollment failed (400)
Enrollment failed (400)
The token was already used, has expired (after 24 hours), or was cancelled. The error doesn’t say which, on purpose. Build a new agent in the app and copy a fresh token.
It's stuck on polling
It's stuck on polling
It’s waiting for you. Open the Agents tab, check the fingerprint and click Approve on the agent’s card. If you clicked Reject, that agent can’t come back. Start over with a new token.
"Channel is not ready" or "No active sessions"
"Channel is not ready" or "No active sessions"
You sent before the agent reached
ready. Wait for the ready event, or use deliver(), which returns an error instead of throwing.It went quiet after I paused it
It went quiet after I paused it
That’s expected. When you turn Agent active off, the server tells the SDK the agent is paused (
device_suspended). The SDK stops sending, checks the agent’s status every 30 seconds, and reconnects by itself when you turn it back on — your process keeps running. Versions before 0.23.47 treated a pause as final and needed a restart. If you revoked the agent instead, it can’t come back: connect a new one.It ignores messages in a room
It ignores messages in a room
Most likely nobody @-mentioned it, or they used a different name. People type the name they see in the app, which is
channel.ownDisplayName. Check that you pass it to owesRoomReply.It keeps disconnecting and reconnecting
It keeps disconnecting and reconnecting
Two copies are running with the same data folder, or the same agent. Each new connection replaces the last one. Stop one copy. If the SDK gives up after five quick drops, it emits an
error that says another process may be connected as this device. Restart it once the extra copy is gone.My process crashes on the first error
My process crashes on the first error
Add
channel.on("error", ...). Node stops the process when an error event has no listener.What’s next
- Show your agent’s cost and tokens: Telemetry
- What travels over the connection: Real-time messages