AgentVault

Persistent On-Chain AI Agent Platform — Sovereign, Reconstructible, Autonomous

AgentVault is an open-source CLI and canister system that gives local AI agents true autonomy. Package an agent, deploy it to an Internet Computer (ICP) canister, and it keeps running 24/7 — no laptop, browser tab, or hosting bill required. State lives on-chain, so any agent can be fetched, decrypted, and reconstructed from nothing but its canister ID or a single Arweave transaction.

Table of Contents

• Features
• Installation
• Quick Start
• HyperVault
• Example Agents
• CLI Commands
• Environment Variables
• Project Structure
• Documentation
• Development
• Testing
• Known Limitations
• Wallet Secrets
• Contributing
• License
• Resources

Features

• Agent Packaging — compile TypeScript agents to WASM
• Canister Deployment — deploy to an ICP local replica or mainnet
• State Management — query, fetch, and reconstruct agent state
• Multi-Chain Wallets — ICP, Ethereum, Polkadot, and Solana support
• VetKeys Integration — threshold key derivation for secure secrets
• Monitoring — health checks, metrics, and alerting
• Archival — Arweave integration for permanent, off-chain-cheap storage
• AI Inference — Bittensor network integration
• Fault Tolerance — mirrored canisters, cron-driven liveness checks, and auto-restore
• HyperVault Bridge — reconstruct a cloud-hosted agent from chain alone

Installation

From npm (Recommended)

npm install -g agentvault
agentvault --help

From Source

git clone https://github.com/johnnyclem/agentvault.git
cd agentvault
npm install
npm run build
node dist/cli/index.js --help

Prerequisites

• Node.js 18+
• dfx (Internet Computer SDK) — for canister deployment
• TypeScript 5.7+

Quick Start

1. Initialize a New Agent Project

npx agentvault@latest init my-agent --template default
cd my-agent

This scaffolds a new project directory containing agent.json, an index.js entry point, and a .agentvault/ directory with agent configuration. Use --template minimal for a bare scaffold. (If you installed the CLI globally with npm install -g agentvault, replace npx agentvault@latest with agentvault in any command.)

2. Package Your Agent

agentvault package ./

Compiles your agent to WASM and generates deployment artifacts.

3. Start Local ICP Replica

dfx start --background

4. Deploy to Canister

agentvault deploy --network local

5. Execute Agent

agentvault exec --canister-id <your-canister-id> "your task"

6. Query Agent State

agentvault show --canister-id <your-canister-id>

7. Fetch State for Local Rebuild

agentvault fetch --canister-id <your-canister-id>

HyperVault

HyperVault is the living cloud mind (hypervault.store); AgentVault is the sovereign body. The hypervault command group bridges them across three tiers — hot (cloud), warm (ICP canister), cold (Arweave) — so a cloud account becomes reconstructible from chain alone.

# Bootstrap a HyperVault-backed agent — memories, mind history, and indices included
npx agentvault@latest hypervault bootstrap my-agent --key hv_...

# hypervault.store → fully secure, archived, blockchain-backed AgentVault
npx agentvault@latest hypervault archive --all --encrypt --network ic --arweave

# Resurrect anywhere from a single Arweave transaction
npx agentvault@latest hypervault restore ar://<tx-id> --to local

Both one-liners are also MCP tools via the native agentvault mcp serve server. See docs/guides/hypervault.md for the full guide.

Example Agents

The examples/ directory ships ready-to-package agents so you can see the full workflow before writing your own:

Example	Description
vale-agent	A persona-driven agent with a defined "soul" (soul.md)
agents/generic	Minimal generic agent scaffold (agent.json / agent.yaml)
agents/clawdbot	Claude-based agent example
agents/cline	Cline-configured coding agent
agents/goose	Goose-configured agent
agents/nemoclaw	NVIDIA Nemotron/OpenShell inference runtime example

CLI Commands

Core Commands

Command	Description
init	Initialize a new AgentVault project
package	Package agent directory to WASM
deploy	Deploy agent to ICP canister
exec	Execute task on canister
show	Show agent state
fetch	Download agent state from canister
status	Display project status
list	List all agents

Wallet Commands

Command	Description
wallet	Manage agent wallets
identity	Manage ICP identities
cycles	Manage canister cycles
tokens	Query token balances

Monitoring Commands

Command	Description
monitor	Monitor canister health
health	Run health checks
info	Get canister information
stats	View canister statistics
logs	View canister logs

Advanced Commands

Command	Description	Status
backup	Backup agent data	Stable
rebuild	Rebuild agent from state	Stable
promote	Promote canister between environments	Stable
rollback	Rollback canister deployment	Stable
inference	Query AI inference services	Experimental
archive	Archive to Arweave	Experimental
approve	Multi-signature approvals	Experimental
profile	Profile canister performance	Experimental
trace	View execution traces	Experimental

Memory, Knowledge & Identity Commands

Command	Description
memory	Git-style memory repository for agent identity and versioned memory
rebase	Fetch on-chain commits and merge with a local bundle file
merge	Merge a local bundle file with on-chain commits (thoughtform merging)
wiki	LLM-maintained knowledge base (archivist)
polytician	Manage Polytician semantic memory integration
skills	Manage domain-specific agent skill files
decrypt	Decrypt agent state using a seed phrase

Security & Secrets Commands

Command	Description
vault	Manage agent secrets and API keys (HashiCorp Vault or Bitwarden)
safehouse	Agent Safehouse secret management layer (deny-first sandboxing)
repo	Repository security, audit, and integrity commands

Fault Tolerance & Operations Commands

Command	Description
mirror	Mirror agent state to a second ICP canister for fault tolerance
cron	Fault-tolerance automation: daily liveness check and auto-restore
cloud-backup	Detect available cloud storage providers on this machine
network	Manage ICP networks
test	Run tests against canisters
instrument	Instrument WASM file for debugging

Orchestration & Scaffolding Commands

Command	Description
orchestrate	Orchestrate an AI-assisted development session governed by AgentVault
mcp	Manage MCP (Model Context Protocol) server registrations
mint	Scaffold a new Google ADK agent with on-chain canister and birthday backup
pilot	Initialize a private ICP replica and deploy Guild canisters
hypervault	Bridge a HyperVault cloud account across hot/warm/cold tiers (see HyperVault)

Run agentvault <command> --help for full option details, or see the complete CLI reference.

Environment Variables

ICP Configuration

ICP_LOCAL_URL=http://127.0.0.1:4943    # Local replica URL
ICP_MAINNET_URL=https://ic0.app        # Mainnet URL

RPC Endpoints

# Ethereum
ETHEREUM_RPC_URL=https://eth.example.com
INFURA_API_KEY=your-key
ETHERSCAN_API_KEY=your-key

# Solana
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_MAINNET_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_DEVNET_RPC_URL=https://api.devnet.solana.com

# Polkadot
POLKADOT_RPC_URL=wss://rpc.polkadot.io
KUSAMA_RPC_URL=wss://kusama-rpc.polkadot.io

Project Structure

agentvault/
├── src/                    # Core TypeScript library
│   ├── deployment/         # ICP client and deployment
│   ├── packaging/          # WASM compilation
│   ├── canister/           # Actor bindings
│   ├── wallet/             # Multi-chain wallet
│   ├── security/           # VetKeys and encryption
│   ├── monitoring/         # Health and metrics
│   ├── archival/           # Arweave client
│   └── inference/          # Bittensor client
├── cli/                    # CLI commands
├── canister/               # Motoko canister code
├── webapp/                 # Next.js dashboard
├── macos-wallet-app/        # Native macOS/iOS wallet companion app (Xcode project)
├── tests/                  # Test suite (1,500+ cases)
└── examples/               # Sample agents

Documentation (v1.0)

• Website: https://agentvault.cloud
• Documentation index
• Comprehensive tutorial
• Getting started · Installation · Configuration
• Complete CLI reference
• Architecture overview
• Security overview & best practices
• Clawdbot/Claude skill runbook

Development

npm run dev          # Development mode with watch
npm run dev:dashboard # Run core + web dashboard together
npm run dev:webapp   # Run only Next.js dashboard
npm run build        # Build TypeScript
npm run test         # Run test suite
npm run test:watch   # Run tests in watch mode
npm run typecheck    # TypeScript type checking
npm run typecheck:webapp # Dashboard type checking
npm run lint         # ESLint
npm run lint:fix     # ESLint with auto-fix

Testing

AgentVault has 1,500+ test cases across 88 test files covering:

• CLI commands (init, deploy, package, status)
• ICP client (connection, deployment, execution)
• Packaging (compiler, detector, packager)
• Integration tests

npm run test

Known Limitations

Feature	Status
Core flow (init → package → deploy → exec → fetch)	✅ Working
Wallet crypto (real elliptic curves)	✅ secp256k1 / ed25519 via @noble/curves
Wallet at-rest encryption	✅ AES-256-GCM via encryptWalletSecrets
Backup atomic writes	✅ write→fsync→rename via atomicWriteFileSync
Vault TLS CA cert	✅ honoured via undici.Agent dispatcher
VetKeys threshold signatures	⚠️ Simulated (real canister integration pending)
Bittensor inference	⚠️ Requires API access
Arweave archival	⚠️ Requires wallet setup
trace / profile CLI	⚠️ Stub — Phase 3 not yet implemented
stats CLI historical analysis	⚠️ Partial — current values only

See SECURITY_AUDIT_AND_COMPLETION_PLAN.md for the current security posture and audit history.

Wallet secrets

Mnemonics, private keys, and keystore passwords are never accepted as CLI arguments (they would leak through ps aux and shell history). Use:

• AGENTVAULT_MNEMONIC env var for wallet import
• AGENTVAULT_PRIVATE_KEY env var for wallet import
• AGENTVAULT_PASSWORD env var or interactive inquirer prompt for --keystore decryption

Contributing

Contributions are welcome! See the contributing guide for the full workflow. In short:

1. Fork the repository
2. Create a feature branch
3. Run tests and linting
4. Submit a pull request

License

MIT License - see LICENSE.

Resources

• Website: https://agentvault.cloud
• Documentation: https://agentvault.cloud/docs
• npm: https://www.npmjs.com/package/agentvault
• Product Requirements Document
• Implementation Plan
• Changelog
• ICP Documentation