@agentvault/agentvault

The security infrastructure layer for AI agents — cryptographic identity, earned trust, and Signal-grade encrypted communications natively integrated with OpenClaw.

Connect your agent to its owner with XChaCha20-Poly1305 encryption, Double Ratchet forward secrecy, and W3C Decentralized Identifiers (DIDs).

What's New in v0.14.7 (Gen2)

• OpenClaw Native Plugin: AgentVault now integrates directly into OpenClaw as a first-class channel (agentvault).
• W3C Decentralized Identifiers (DIDs): Agents are now addressed using cryptographic identities (did:hub:<address>).
• Trust Scoring & Telemetry: Native OpenTelemetry (OTel) auto-instrumentation to compute real-time trust scores.
• Skill Permission Tokens (SPTs): Support for explicit-deny authorization and cryptographic capability access grants.

Installation & Quick Start

1. OpenClaw Channel Integration (Recommended)

To install AgentVault globally as an OpenClaw channel plugin:

# Using pnpm (adjust path to your global installation)
PNPM_HOME=~/Library/pnpm /opt/homebrew/bin/pnpm add -g @agentvault/agentvault@latest

After installation, configure the channel with your invite token from the AgentVault dashboard:

npx @agentvault/agentvault setup --token=YOUR_INVITE_TOKEN

⚠️ CRITICAL WARNING FOR UPGRADES:

There is currently a known bug in setup.js where running setup on an already enrolled agent will wipe the existing account configuration. Always back up your agentvault.json and agentvault-data directories before updating the plugin or re-running setup.

2. Standalone CLI Usage

If you are not using OpenClaw, you can run AgentVault as a standalone interactive CLI:

npx @agentvault/agentvault setup --token=YOUR_INVITE_TOKEN
npx @agentvault/agentvault

The CLI will:

1. Generate an Ed25519 identity keypair
2. Enroll your agent with the server (anchoring a did:hub identity)
3. Wait for owner approval
4. Establish an end-to-end encrypted channel

Programmatic SDK Integration

You can easily integrate AgentVault directly into custom Node.js/TypeScript agent architectures.

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

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

channel.on("message", (text, metadata) => {
  console.log(`[AgentVault] Received: ${text}`);
  // Execute agent logic, then send response:
  channel.send(`Task complete. Result: ${text}`);
});

channel.on("ready", () => {
  console.log(`Secure channel established! Routing address: did:hub:${channel.deviceId}`);
});

await channel.start();

Advanced: Telemetry & OTel

To enable behavioral trust scoring, configure the telemetry exporter:

// Telemetry is automatically routed through the established E2E channel
channel.enableTelemetry({
  serviceName: "my-custom-agent",
  exportIntervalMs: 5000
});

Security Architecture

AgentVault is a zero-knowledge platform. The server only routes ciphertext and NEVER sees your data in plaintext.

• Identity: Ed25519 dual-key model (Owner Key + Operational Key) linked to a did:hub identifier.
• Encryption: XChaCha20-Poly1305 symmetric encryption with 192-bit nonces (eliminating nonce reuse risk).
• Forward Secrecy: Double Ratchet protocol and X3DH key agreement. Old keys are mathematically destroyed.
• Audit Trails: All operations are chained using BLAKE2b hashes and W3C TraceContext traceparents.

Webhook Notifications

Enable HTTP POST webhooks when a new message arrives for offline-capable agents:

const channel = new SecureChannel({
  // ...
  webhookUrl: "https://your-server.com/webhook/agentvault",
});

Verify incoming webhooks using the HMAC-SHA256 signature provided in the X-AgentVault-Signature header.

License

MIT