Skip to main content

​
v0 Integration

Oxy integrates with v0.dev to enable AI-powered data application creation. The v0 integration allows agents to generate interactive dashboards and visualizations using natural language.

​
Overview

The v0 integration provides a create_v0_app tool that agents can use to build data applications. When an agent needs to create a visualization or dashboard, it can leverage v0’s generative UI capabilities to create interactive React components that query data using the Oxy SDK.

​
Prerequisites

Before using the v0 integration, you need:
  1. Oxy CLI: Install the Oxy CLI by following the installation guide
  2. v0 API Key: Get your API key from v0.dev/chat/settings/keys

​
Configuration

​
1. Set up Environment Variable

Export your v0 API key as an environment variable: 
export V0_API_KEY="your-v0-api-key-here"
To persist this across terminal sessions, add it to your shell profile: 
# For bash
echo 'export V0_API_KEY="your-v0-api-key-here"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export V0_API_KEY="your-v0-api-key-here"' >> ~/.zshrc
source ~/.zshrc

​
2. Configure Oxy API URL (Optional)

When v0 creates data applications, they need to connect to your Oxy API to query data using the Oxy SDK. By default, the integration assumes your Oxy API is running at http://127.0.0.1:3000/api (local development).
Important: Use 127.0.0.1 instead of localhost for local development. v0 blocks URLs without dots in the hostname for security reasons, so localhost will not work.
If you’re running the Oxy web app on a different host or port, set the OXY_API_URL environment variable: 
# For local development (default, can be omitted)
# Note: Use 127.0.0.1, not localhost - v0 blocks URLs without dots
export OXY_API_URL="http://127.0.0.1:3000/api"

# For production or custom deployment
export OXY_API_URL="https://your-oxy-instance.com/api"

# For custom local port (still use 127.0.0.1)
export OXY_API_URL="http://127.0.0.1:8080/api"
To persist this across terminal sessions: 
# For bash
echo 'export OXY_API_URL="https://your-oxy-instance.com/api"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export OXY_API_URL="https://your-oxy-instance.com/api"' >> ~/.zshrc
source ~/.zshrc

​
3. Configure Agent with v0 Tool

In your agent configuration file (e.g., v0.agent.yml), add the create_v0_app tool: 
tools:
  - name: v0_app
    type: create_v0_app
You can see a complete example in crates/app/demo_project/v0.agent.yml.

​
Running Oxy with v0 Integration

​
Quick Start

  1. Set up environment variables:
# Required: v0 API key
export V0_API_KEY="your-v0-api-key-here"

# Optional: Oxy API URL (defaults to http://127.0.0.1:3000/api)
# Only needed if your Oxy web app runs on a different host/port
# Important: Use 127.0.0.1, not localhost (v0 blocks URLs without dots)
export OXY_API_URL="http://127.0.0.1:3000/api"
  1. Navigate to a project with v0-enabled agent configuration:
cd crates/app/demo_project
  1. Run the agent:
# Using debug build (recommended for development)
cargo build -p oxy
./target/debug/oxy agent run v0.agent.yml
  1. Interact with the agent:
What would you like me to help you with?
> Create a dashboard showing weekly sales trends by store
The agent will:
  • Analyze your request
  • Query the data using SQL
  • Persist the results
  • Generate a v0 app with interactive visualizations
  • Return a URL to your data application

​
How It Works

​
Data App Creation Flow

When you ask the agent to create a data application:
  1. Data Preparation: The agent uses execute_sql tool with the persist flag to prepare data tables
  2. Schema Definition: The agent formats table schemas for v0: 
    - table_name: sales_trends
  file_path: tables/0.parquet
  columns:
    Date: date
    Weekly_Sales: float
    Store: string
  3. v0 Prompt: The agent sends a detailed prompt to v0 with:
    • Your visualization requirements
    • Available data tables and their schemas
    • Instructions to use Oxy SDK for querying
  4. Environment Configuration: The integration automatically configures the v0 project with:
    • OXY_URL: Your Oxy API endpoint (from OXY_API_URL env var)
    • OXY_PROJECT_ID: Your current project ID
    • OXY_API_KEY: Optional API key for authentication
  5. App Generation: v0 generates a React application with the Oxy SDK integrated
  6. Deployment: The app is deployed and a URL is returned

​
Example Interaction

User: Create a dashboard to compare sales performance across all stores

Agent: I'll create a dashboard for you. First, let me query the data...

[Executes SQL to aggregate sales by store]

Now I'll create a dashboard with this data:
  - table_name: store_performance
    file_path: tables/0.parquet
    columns:
      Store: integer
      Total_Sales: float
      Avg_Weekly_Sales: float
      Week_Count: integer

[Calls v0_app tool]

Your dashboard is ready! View it here: https://v0.dev/chat/...

​
Best Practices

​
1. Persist Data Before Creating Apps

Always use the persist flag when executing SQL for v0 apps: 
# In agent instructions
1. ALWAYS use `execute_sql` tool with the persist flag to prepare data
2. Then pass the persisted table paths to v0_app

​
2. Provide Clear Schema Information

Help v0 understand your data by providing clear column names and types: 
- table_name: sales_metrics
  file_path: tables/0.parquet
  columns:
    date: date          # Use descriptive types
    revenue: float      # Not just "number"
    store_id: string    # Be specific

​
3. Include Oxy SDK Instructions

When prompting v0, always mention using the Oxy SDK: 
Create a dashboard to visualize weekly sales trends.
Use the following data: [tables...]

Make sure to use Oxy SDK to query the data.

​
Troubleshooting

​
”V0_API_KEY environment variable not set”

Solution: Make sure you’ve exported the V0_API_KEY environment variable: 
export V0_API_KEY="your-key"
Verify it’s set: 
echo $V0_API_KEY

​
v0 app not using Oxy SDK

Solution: Ensure your agent’s system instructions include guidance to prompt v0 with SDK usage instructions. See the example in crates/app/demo_project/v0.agent.yml:108.

​
Data not loading in the app

Solution: Make sure data was persisted correctly before calling v0_app. Check that:
  1. execute_sql was called with persist: true
  2. The file paths in the v0 prompt match the persisted table locations
  3. The schema information is accurate

​
v0 app cannot connect to Oxy API

Problem: The generated v0 app shows connection errors or cannot fetch data from the Oxy SDK. Solution: Verify that the OXY_API_URL environment variable is set correctly:
  1. Check if OXY_API_URL is set: 
    echo $OXY_API_URL
  2. For local development with Oxy web app, ensure it matches where your web app is running: 
    # Correct - use 127.0.0.1 for local development
export OXY_API_URL="http://127.0.0.1:3000/api"

# WRONG - v0 blocks URLs without dots (localhost will not work)
# export OXY_API_URL="http://localhost:3000/api"
  3. For production deployments, use your public Oxy instance URL: 
    export OXY_API_URL="https://your-oxy-instance.com/api"
  4. Make sure the Oxy web app is actually running at the specified URL
  5. Verify you’re using 127.0.0.1 instead of localhost for local development (v0 security restriction)
  6. Check that the v0 app can reach the Oxy API (firewall, CORS, network access)

​
Example Agent Configuration

Here’s a minimal agent configuration with v0 integration: 
model: "openai-4o-mini"
name: analytics-agent

description: |
  An agent that creates data visualizations using v0.

tools:
  - type: execute_sql
    name: execute_sql
    database: local

  - name: v0_app
    type: create_v0_app

system_instructions: |
  When creating data apps:
  1. First use execute_sql with persist flag to prepare data
  2. Format table schemas clearly for v0
  3. Prompt v0 to use Oxy SDK for data queries
  4. Return the app URL to the user

​
Next Steps

​
Reference