Skip to main content

​
Overview

This guide will help you run the complete MetaVault AI stack locally, including:
  1. Local blockchain with deployed smart contracts
  2. AI agent server for vault management
  3. Next.js frontend for user interaction

​
Running the Full Stack

1

Start Smart Contracts

Navigate to the contracts directory and start a local Hardhat node:
cd packages/contracts
First, compile the smart contracts:
pnpm hardhat compile
Then start the local blockchain:
pnpm hardhat node
Keep this terminal window open. The local blockchain will run on http://127.0.0.1:8545
2

Deploy Contracts

In a new terminal, deploy the mock contracts to your local blockchain:
cd packages/contracts

pnpm hardhat run scripts/deploy_mocks.ts --network localhost
Save the deployed contract addresses from the output. You’ll need them for configuration.
3

Configure AI Agents

Set up the environment for the AI agents:
cd packages/agents/defi-portfolio
cp .env.example .env
Edit the .env file and add your configuration. See the Configuration guide for details.
At minimum, you need to configure:
  • OPEN_ROUTER_KEY - Your OpenRouter API key
  • VAULT_ADDRESS - From the deployment output
  • RPC_URL - Set to http://127.0.0.1:8545
4

Start AI Agent Server

Run the agent server:
cd packages/agents/defi-portfolio

pnpm run dev
The agent server will start and be available for the frontend to communicate with.
To run the automation cron job (for strategy monitoring), use:
pnpm run automate:cron
5

Configure Frontend

Set up the environment for the frontend:
cd packages/frontend
cp .env.example .env.local
Update the .env.local file with the contract addresses from Step 2:
NEXT_PUBLIC_VAULT_ADDRESS=0x...
NEXT_PUBLIC_ROUTER_ADDRESS=0x...
NEXT_PUBLIC_STRATEGY_LEVERAGE_ADDRESS=0x...
NEXT_PUBLIC_STRATEGY_AAVE_ADDRESS=0x...
NEXT_PUBLIC_LINK_ADDRESS=0x...
6

Start Frontend

Launch the Next.js development server:
cd packages/frontend

pnpm dev
Open http://localhost:3000 in your browser to access MetaVault AI.

​
Quick Start with All Services

Alternatively, you can start all services at once from the root directory: 
pnpm dev:all
This will concurrently run:
  • Local Hardhat node (contracts)
  • AI agent server
  • Next.js frontend
You still need to manually deploy contracts and configure environment variables before using this command.

​
Verify Everything is Running

Confirm that all services are operational:
Your Hardhat node terminal should show:
Started HTTP and WebSocket JSON-RPC server at http://127.0.0.1:8545/
The agent server should be listening on the configured port (default: 3001):
Agent server running on port 3001
The Next.js server should display:
Ready - started server on 0.0.0.0:3000, url: http://localhost:3000

​
Connect Your Wallet

To interact with MetaVault AI:
  1. Open MetaMask and add the local Hardhat network:
    • Network Name: Hardhat Local
    • RPC URL: http://127.0.0.1:8545
    • Chain ID: 31337
    • Currency Symbol: ETH
  2. Import one of the test accounts from the Hardhat node output (it provides 20 pre-funded accounts)
  3. Connect your wallet on the MetaVault AI frontend

​
Next Steps

Configuration Guide

Detailed configuration options for all packages

Architecture

Learn about MetaVault AI’s system architecture

AI Agents

Explore the AI agents that manage your vault

Smart Contracts

Understand the vault’s smart contract system

Build docs developers (and LLMs) love

Get started for freeTalk to us