Skip to main content
Follow this guide to run existing vibekit agents or build your own.

​
Prerequisites

Make sure you have Docker Desktop with Docker Compose v2.24 or greater installed on your system.
If you are on an M-series Mac, you need to install Docker using the dmg package supplied officially by Docker rather than through Homebrew or other means to avoid build issues.

​
Get the Code

To get started, clone the repository through the command line or your preferred IDE: 
git clone https://github.com/EmberAGI/arbitrum-vibekit.git &&
cd arbitrum-vibekit

​
Run DeFi Agents

The swapping and lending agents start automatically when you launch the Vibekit frontend. Follow the steps below to get everything up and running.
1

Configure Environment Variables

Navigate to the typescript directory and create a .env file by copying the .env.example and filling in the required values:
cd typescript &&
cp .env.example .env
At a minimum, you need:
  • Your preferred AI provider API key (e.g., OPENROUTER_API_KEY, OPENAI_API_KEY)
  • Generate a secure AUTH_SECRET
2

Start Services

# Ensure you are in the typescript/ directory
# Start the web frontend and default agents
docker compose up
If you previously ran docker compose up with an older version of the Vibrekit and encountered frontend errors or database-related errors in the docker service logs, follow these steps:
  1. Clear your browser cache.
  2. Run the following command in your terminal: 
    docker compose down && docker volume rm typescript_db_data && docker compose build web --no-cache && docker compose up
3

Access the Web Interface

Once all services are running, open your browser and navigate to http://localhost:3000. To be able to chat with the agents, you need to connect your wallet first. Click on “Connect Wallet” to get started:Wallet Setup PnAfter setting up your wallet, you’ll see the Vibekit web interface, where you can explore different agent capabilities:Chat Interface Pn

​
Build Your Own Agent

To build your own agent, we recommend using our quickstart agent template. It provides all the necessary boilerplate code so you can start building right away. Follow these steps to integrate and run the quickstart agent:
1

Enable quickstart agent

Let’s enable the quickstart agent on the frontend. In the agents-config.ts file, uncomment the agent’s configuration in two places:
...
  {
    id: 'quickstart-agent-template' as const,
    name: 'Quickstart',
    description: 'Quickstart agent',
    suggestedActions: [],
  },
...

...
  ['quickstart-agent-template', 'http://quickstart-agent-template:3007/sse'],
...
2

Add Agent to Docker Compose

In the docker compose file, uncomment the service definition for the quickstart agent:
---
quickstart-agent-template:
  build:
    context: ./
    dockerfile: templates/quickstart-agent/Dockerfile
  container_name: vibekit-quickstart-agent-template
  env_file:
    - path: .env
      required: true
    - path: templates/quickstart-agent/.env
      required: false
  ports:
    - 3007:3007
  restart: unless-stopped
3

Configure Agent's Environment

Navigate to the agent’s directory and create a local .env by copying the.env.example file. Make sure to populate the .env file with your API keys and configurations:
cd typescript/templates/quickstart-agent && cp .env.example .env
4

Rebuild and Restart Services

Navigate to the typescript directory, rebuild the web application and restart all services to apply the changes:
cd ../.. &&
docker compose build web --no-cache && docker compose up
The quickstart agent is now accessible through the web frontend. You can now modify the agent to implement your logic. Make sure to rebuild services after your changes.
To learn more about Vibekit’s agent configurations, refer to this guide.
⌘I