Quick Start

Get MetaVault AI up and running on your local machine

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

   pnpm hardhat compile
   

   npm run hardhat compile
   

   yarn hardhat compile
   

   Then start the local blockchain:

   pnpm

   pnpm hardhat node
   

   npm run hardhat node
   

   yarn 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

   pnpm hardhat run scripts/deploy_mocks.ts --network localhost
   

   npm run hardhat run scripts/deploy_mocks.ts --network localhost
   

   yarn 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

   pnpm run dev
   

   npm run dev
   

   yarn 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

   pnpm dev
   

   npm run dev
   

   yarn 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

pnpm dev:all

npm run dev:all

yarn 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:

Check Blockchain

Your Hardhat node terminal should show:

Started HTTP and WebSocket JSON-RPC server at http://127.0.0.1:8545/

Check AI Agents

The agent server should be listening on the configured port (default: 3001):

Agent server running on port 3001

Check Frontend

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