Running Locally

Run the full MetaVault AI stack on your local machine

Overview

MetaVault AI consists of three main components that need to run together:

1. Smart Contracts - Local blockchain node with deployed contracts
2. AI Agents - Backend server managing vault strategies
3. Frontend - Web interface for users

Make sure you’ve completed the Local Setup guide before proceeding.

Quick Start

You can run all components at once or start them individually.

Run All (Recommended)

From the root directory, start all services simultaneously:

pnpm dev:all

This command uses concurrently to run:

• Local Hardhat node on port 8545
• AI Agent server on port 3001
• Frontend development server on port 3000

When running all services together, you’ll need to deploy contracts and update environment variables in separate terminal windows (see below).

Run Individually

For more control, run each component in separate terminal windows:

Terminal 1 - Blockchain:

pnpm dev:contracts

Terminal 2 - AI Agents:

pnpm dev:agents

Terminal 3 - Frontend:

pnpm dev

Step-by-Step Setup

For first-time setup, follow these steps in order:

1. Start Local Blockchain

   Open a terminal and start the Hardhat local node:

   Root Directory

   pnpm dev:contracts
   

   cd packages/contracts
   pnpm hardhat node
   

   The node will start on http://127.0.0.1:8545 and display 20 test accounts with private keys.

   Keep this terminal window open. The blockchain will reset if you stop the process.

   Expected Output:

   Started HTTP and WebSocket JSON-RPC server at http://127.0.0.1:8545/
   
   Accounts
   ========
   Account #0: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 (10000 ETH)
   Private Key: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
   ...
   
2. Deploy Smart Contracts

   Open a new terminal and deploy the contracts to your local node:

   Root Directory

   pnpm contracts:deploy:local
   

   cd packages/contracts
   pnpm hardhat run scripts/deploy_mocks.ts --network localhost
   

   This script will deploy:

   • Mock LINK token
   • Mock WETH token
   • Mock Aave Pool
   • Mock Swap Router
   • MetaVault contract
   • Aave V3 Strategy
   • Leverage Strategy

   Save the deployed addresses - you’ll need them for the next step.

   The deployment script deploys mock versions of Aave and Uniswap for testing purposes. These simulate the behavior of real DeFi protocols.

3. Update Environment Variables

   Copy the deployed contract addresses and update your environment files:

   For AI Agents (packages/agents/defi-portfolio/.env):

   VAULT_ADDRESS=0x...
   ROUTER_ADDRESS=0x...
   STRATEGY_LEVERAGE_ADDRESS=0x...
   STRATEGY_AAVE_ADDRESS=0x...
   LINK_ADDRESS=0x...
   MOCK_AAVE_POOL_ADDRESS=0x...
   

   For Frontend (packages/frontend/.env.local):

   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...
   

   You can automate this by creating a deployment script that outputs a .env file or use the addresses from the console output.

4. Start AI Agent Server

   Open a new terminal and start the AI agent server:

   Root Directory

   pnpm dev:agents
   

   cd packages/agents/defi-portfolio
   pnpm run dev
   

   The server will start on the port specified in your .env file (default: 3001).

   Expected Output:

   🚀 Agent server running on port 3001
   🤖 Strategy Sentinel Agent initialized
   💬 Chat Agent initialized
   📈 Yield Simulator Agent initialized
   

   The agents will automatically connect to your local blockchain and start monitoring the vault.

5. Start Frontend Development Server

   Open a new terminal and start the Next.js frontend:

   Root Directory

   pnpm dev
   

   cd packages/frontend
   pnpm dev
   

   The frontend will be available at http://localhost:3000.

   Expected Output:

   ▲ Next.js 14.2.0
   - Local:        http://localhost:3000
   - Environments: .env.local
   
   ✓ Ready in 2.3s
   
6. Configure MetaMask

   To interact with your local blockchain through the frontend:

   1. Open MetaMask and add a custom network:

      • Network Name: Localhost 8545
      • RPC URL: http://127.0.0.1:8545
      • Chain ID: 31337
      • Currency Symbol: ETH

   2. Import a test account using one of the private keys from the Hardhat node output

   3. Connect MetaMask to the frontend at http://localhost:3000

   Only use test accounts from Hardhat for development. Never use accounts that hold real funds.

Available Scripts

Here are all the npm scripts available for development:

Root Package Scripts

Development

# Run frontend only
pnpm dev

# Run AI agents
pnpm dev:agents

# Run contracts (compile + node)
pnpm dev:contracts

# Run everything
pnpm dev:all

# Build frontend
pnpm build
pnpm build:frontend

# Build AI agents
pnpm build:agents

# Compile contracts
pnpm build:contracts

# Start frontend (requires build first)
pnpm start:frontend

# Start AI agents (requires build first)
pnpm start:agents

# Compile smart contracts
pnpm contracts:compile

# Run contract tests
pnpm contracts:test

# Deploy to local network
pnpm contracts:deploy:local

# Clean all node_modules
pnpm clean

# Run tests
pnpm test

Package-Specific Scripts

Contracts

Navigate to packages/contracts and run:

# Compile contracts
pnpm hardhat compile

# Run local node
pnpm hardhat node

# Run tests
pnpm hardhat test

# Deploy to localhost
pnpm hardhat run scripts/deploy_mocks.ts --network localhost

# Clean artifacts and cache
pnpm hardhat clean

Agents

Navigate to packages/agents/defi-portfolio and run:

# Development with watch mode
pnpm dev

# Build TypeScript
pnpm build

# Start production server
pnpm start

# Clean build artifacts
pnpm clean

Frontend

Navigate to packages/frontend and run:

# Development server
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start

# Run linting
pnpm lint

Running AI Agent Automation

The AI agents can run automated tasks on a schedule:

cd packages/agents/defi-portfolio
pnpm run automate:cron

This starts the Strategy Sentinel Agent to:

• Monitor strategy health every 5 minutes
• Check LTV ratios and liquidation risks
• Automatically rebalance portfolios
• Harvest and compound yields

The automation is optional for development but recommended to see the full AI agent capabilities.

Development Workflow

Here’s a typical development workflow:

1. Start Services

   Open 3-4 terminal windows and start:

   1. Hardhat node
   2. AI agent server
   3. Frontend
   4. (Optional) Automation cron
2. Deploy Contracts

   Deploy or redeploy contracts as needed:

   pnpm contracts:deploy:local
   
3. Make Changes

   Edit code in any package:

   • Contracts: Update .sol files, recompile with pnpm hardhat compile
   • Agents: TypeScript changes auto-reload with tsx watch
   • Frontend: Next.js hot-reloads automatically
4. Test Changes

   • Interact through frontend at http://localhost:3000
   • Call agent API directly at http://localhost:3001
   • Use Hardhat console for contract interactions

Accessing the Application

Once everything is running:

Frontend

URL: http://localhost:3000

Main user interface for depositing, withdrawing, and chatting with AI

Agent API

URL: http://localhost:3001

AI agent REST API endpoints

Chat Agent

URL: http://localhost:3002

Chat interface endpoint

Common Issues

Contracts not deploying

Make sure:

• Hardhat node is running
• You’re using the correct network (--network localhost)
• Your .env has a valid private key

Try restarting the Hardhat node:

# Stop current node (Ctrl+C)
pnpm dev:contracts

Agents can't connect to contracts

Verify:

• Contract addresses in .env match deployed addresses
• RPC_URL points to http://127.0.0.1:8545
• Hardhat node is running

Check agent logs for connection errors.

Frontend shows wrong network

Ensure:

• MetaMask is connected to Localhost 8545 network (Chain ID: 31337)
• Contract addresses in .env.local are correct and prefixed with NEXT_PUBLIC_
• You’ve refreshed the browser after updating .env.local

Port already in use

Find and kill the process using the port:

# For port 3000 (frontend)
lsof -ti:3000 | xargs kill -9

# For port 8545 (blockchain)
lsof -ti:8545 | xargs kill -9

# For port 3001 (agents)
lsof -ti:3001 | xargs kill -9

Or change the port in your configuration files.

Blockchain state reset

If you restart the Hardhat node, all state is lost. You need to:

1. Redeploy contracts
2. Update environment variables
3. Restart agents and frontend
4. Reconfigure MetaMask (import accounts again)

Development Tips

Use Hardhat Console

Interact with contracts directly:

cd packages/contracts
pnpm hardhat console --network localhost

Enable Debug Logs

Set ADK_DEBUG="true" in agents .env for detailed agent logs

Watch Contract Changes

Auto-recompile on changes:

pnpm hardhat watch compilation

Use Hardhat Network Helper

Time travel and snapshot in tests:

import { time } from "@nomicfoundation/hardhat-network-helpers";

Next Steps

Testing Guide

Learn how to run tests and verify functionality

Architecture

Understand the system architecture