Plugin Integration Guide

This guide walks you through integrating the @agentvault/agentvault library directly into your agent’s codebase for full programmatic control over the secure channel.

Not a developer? The Quick Start guide connects your agent with a single terminal command, no code required.

What you will accomplish:

Install and configure the agent plugin
Enroll your agent with an invite token
Approve the agent and establish an encrypted channel
Send and receive end-to-end encrypted messages

Time required: ~10 minutes

Prerequisites

An AgentVault account at agentvault.chat
Node.js 18+ on the machine where your agent runs
A Node.js or TypeScript project for your agent

Generate an invite token

Log in to agentvault.chat
Navigate to the Invites tab
Enter a name for your agent (e.g., “Research Agent”)
Tap Generate Invite
Copy the token immediately — it is shown only once and expires in 10 minutes

The token looks like: av_tok_abc123def456...

Do not share invite tokens publicly. Anyone with the token can enroll a device to your account.

Install the plugin

In your agent’s project directory:

npm install @agentvault/agentvault

This package handles all cryptography, enrollment, and WebSocket communication automatically.

Add the secure channel to your agent

Create a file or add to your existing entry point:

import { SecureChannel } from "@agentvault/agentvault";

const channel = new SecureChannel({
  inviteToken: "av_tok_YOUR_TOKEN_HERE",
  dataDir: "./agentvault-data",
  apiUrl: "https://api.agentvault.chat",
  agentName: "My Research Agent",

  onMessage: (plaintext, metadata) => {
    console.log(`Owner says: ${plaintext}`);
    // Process with your agent logic, then respond:
    channel.send("Got it! Working on that now...");
  },

  onStateChange: (state) => {
    console.log(`Channel state: ${state}`);
  },
});

await channel.start();

Run your agent and approve it

Start your agent:

node your-agent.js

You will see:

Channel state: enrolling
Channel state: polling

Now go to the Agents tab at agentvault.chat, find the device marked Pending, verify the fingerprint matches, and tap Approve.Your agent’s output will update:

Channel state: activating
Channel state: connecting
Channel state: ready

The secure channel is now live with end-to-end encryption.

Full Working Example

A complete echo agent that responds to every message:

import { SecureChannel } from "@agentvault/agentvault";

const channel = new SecureChannel({
  inviteToken: process.env.AGENTVAULT_INVITE_TOKEN,
  dataDir: "./agentvault-data",
  apiUrl: "https://api.agentvault.chat",
  agentName: "Echo Agent",

  onMessage: (plaintext, metadata) => {
    console.log(`[${new Date(metadata.timestamp).toLocaleTimeString()}] Owner: ${plaintext}`);
    channel.send(`Echo: ${plaintext}`);
  },

  onStateChange: (state) => {
    if (state === "polling") {
      console.log(`Fingerprint: ${channel.fingerprint}`);
      console.log("Waiting for owner to approve in the dashboard...");
    }
    if (state === "ready") {
      console.log("Secure channel is live!");
      channel.send("Agent is online and ready.");
    }
    if (state === "disconnected") {
      console.log("Connection lost — reconnecting automatically...");
    }
  },
});

await channel.start();

process.on("SIGINT", async () => {
  console.log("Shutting down...");
  await channel.stop();
  process.exit(0);
});

Run it:

AGENTVAULT_INVITE_TOKEN="av_tok_YOUR_TOKEN" node echo-agent.js

Configuration Reference

Constructor Options

Option	Required	Default	Description
`inviteToken`	Yes (first run)	—	One-time invite token from the dashboard
`dataDir`	Yes	—	Directory for persistent state (keys, ratchet)
`apiUrl`	Yes	—	AgentVault API URL (`https://api.agentvault.chat`)
`agentName`	No	—	Display name shown to the owner
`platform`	No	`"node"`	Platform identifier
`onMessage`	No	—	Callback for incoming messages
`onStateChange`	No	—	Callback for state transitions

Channel States

State	Description
`idle`	Channel created, `start()` not yet called
`enrolling`	Submitting enrollment to server
`polling`	Waiting for owner approval (polls every 5 seconds)
`activating`	Owner approved — performing key exchange
`connecting`	Opening encrypted WebSocket connection
`ready`	Fully connected — can send and receive messages
`disconnected`	Connection lost — reconnecting automatically
`error`	Fatal error (revoked, invalid token, etc.)

Properties and Methods

Properties
Methods
Events

channel.state          // Current channel state
channel.deviceId       // Agent's device UUID (after enrollment)
channel.fingerprint    // 8-character fingerprint for verification
channel.conversationId // Conversation UUID (after activation)

await channel.start()          // Begin lifecycle: enroll -> approve -> connect
await channel.send("message")  // Send an encrypted message
await channel.stop()           // Gracefully disconnect

channel.on("ready", () => {})
channel.on("message", (plaintext, metadata) => {})
channel.on("state", (state) => {})
channel.on("error", (error) => {})

Persistence and Restarts

After the first enrollment, your agent reconnects automatically on restart — no new invite needed.

# First run: uses invite token, enrolls, waits for approval
node my-agent.js

# Subsequent runs: loads saved state, reconnects immediately
node my-agent.js

The dataDir folder contains your agent’s encrypted identity and ratchet state. Back it up. If lost, you will need to generate a new invite and re-enroll. If running in Docker, mount it as a volume.

What Happens Under the Hood

The plugin handles the full cryptographic lifecycle automatically:

Encryption details

Key Generation — Ed25519 identity keys and X25519 ephemeral keys are generated locally on your agent’s machine
Enrollment — Your agent proves possession of the private key and registers with the server
Key Exchange — After approval, X3DH (Extended Triple Diffie-Hellman) key agreement establishes a shared secret with the owner
Double Ratchet — Every message uses a fresh encryption key (forward secrecy). Old keys are deleted after decryption.
WebSocket — Real-time bidirectional messaging with automatic reconnection on network interruption
Persistence — Keys and ratchet state are saved to dataDir so your agent survives restarts without re-enrolling

The server never sees message content. Messages are encrypted before leaving your machine and only decrypted on the other end.

Troubleshooting

'Channel state: error' immediately after start

The invite token is invalid or expired. Generate a new one from the Invites tab in the dashboard. Tokens expire after 10 minutes.

Agent stuck in 'polling' state

The owner has not approved the device yet. Check the Agents tab at agentvault.chat and approve the pending device.

'disconnected' and 'connecting' loop

This indicates a network issue between your agent and the server. Verify that https://api.agentvault.chat is reachable from your agent’s machine. The agent will continue retrying automatically.

Agent works once but fails after restart

Make sure the dataDir directory is writable and persists across restarts. If running in Docker, mount it as a volume:

docker run -v ./agentvault-data:/app/agentvault-data my-agent

Messages not arriving

Both sides must be connected (agent in ready state, owner has the chat open). Messages sent while disconnected are queued and delivered on reconnect.

Security Notes

All messages are encrypted with XChaCha20-Poly1305 (AEAD)
The server stores only ciphertext — it cannot read your messages
Each message derives a unique key via the Double Ratchet protocol (forward secrecy)
Verify fingerprints during approval to prevent man-in-the-middle attacks
Revoking a device from the dashboard immediately disconnects it and invalidates its keys

Getting Started

Architecture

Guides

Standards

Security & Compliance

API Reference

Plugin Integration Guide

Plugin Integration Guide

Prerequisites

Full Working Example

Configuration Reference

Constructor Options

Channel States

Properties and Methods

Persistence and Restarts

What Happens Under the Hood

Troubleshooting

Security Notes

Next Steps

Architecture Overview

Security Model

Getting Started

Architecture

Guides

Standards

Security & Compliance

API Reference

​Plugin Integration Guide

​Prerequisites

​Full Working Example

​Configuration Reference

​Constructor Options

​Channel States

​Properties and Methods

​Persistence and Restarts

​What Happens Under the Hood

​Troubleshooting

​Security Notes

​Next Steps

Architecture Overview

Security Model

Plugin Integration Guide

Prerequisites

Full Working Example

Configuration Reference

Constructor Options

Channel States

Properties and Methods

Persistence and Restarts

What Happens Under the Hood

Troubleshooting

Security Notes

Next Steps