v0 Integration

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

Prerequisites

Before using the v0 integration, you need:

Oxygen CLI: Install the Oxygen CLI by following the installation guide
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 Oxygen API URL (Optional)

When v0 creates data applications, they need to connect to your Oxygen API to query data using the Oxygen SDK. By default, the integration assumes your Oxygen 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 Oxygen 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 Oxygen with v0 Integration

Quick Start

Set up environment variables:

# Required: v0 API key
export V0_API_KEY="your-v0-api-key-here"

# Optional: Oxygen API URL (defaults to http://127.0.0.1:3000/api)
# Only needed if your Oxygen 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"

Navigate to a project with v0-enabled agent configuration:

cd crates/app/demo_project

Run the agent:

# Using debug build (recommended for development)
cargo build
./target/debug/oxy agent run v0.agent.yml

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:

Data Preparation: The agent uses execute_sql tool with the persist flag to prepare data tables

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

v0 Prompt: The agent sends a detailed prompt to v0 with:
- Your visualization requirements
- Available data tables and their schemas
- Instructions to use Oxygen SDK for querying
Environment Configuration: The integration automatically configures the v0 project with:
- OXY_URL: Your Oxygen API endpoint (from OXY_API_URL env var)
- OXY_PROJECT_ID: Your current project ID
- OXY_API_KEY: Optional API key for authentication
App Generation: v0 generates a React application with the Oxygen SDK integrated
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 Oxygen SDK Instructions

When prompting v0, always mention using the Oxygen SDK:

Create a dashboard to visualize weekly sales trends.
Use the following data: [tables...]

Make sure to use Oxygen 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 Oxygen 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:

execute_sql was called with persist: true
The file paths in the v0 prompt match the persisted table locations
The schema information is accurate

v0 app cannot connect to Oxygen API

Problem: The generated v0 app shows connection errors or cannot fetch data from the Oxygen SDK. Solution: Verify that the OXY_API_URL environment variable is set correctly:

Check if OXY_API_URL is set:
echo $OXY_API_URL

For local development with Oxygen 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"

For production deployments, use your public Oxygen instance URL:
export OXY_API_URL="https://your-oxy-instance.com/api"
Make sure the Oxygen web app is actually running at the specified URL
Verify you’re using 127.0.0.1 instead of localhost for local development (v0 security restriction)
Check that the v0 app can reach the Oxygen 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 Oxygen SDK for data queries
  4. Return the app URL to the user

Next Steps

Explore the complete v0 agent example
Learn about SQL execution and persistence
Read about agent configuration

​v0 Integration

​Overview

​Prerequisites

​Configuration

​1. Set up Environment Variable

​2. Configure Oxygen API URL (Optional)

​3. Configure Agent with v0 Tool

​Running Oxygen with v0 Integration

​Quick Start

​How It Works

​Data App Creation Flow

​Example Interaction

​Best Practices

​1. Persist Data Before Creating Apps

​2. Provide Clear Schema Information

​3. Include Oxygen SDK Instructions

​Troubleshooting

​”V0_API_KEY environment variable not set”

​v0 app not using Oxygen SDK

​Data not loading in the app

​v0 app cannot connect to Oxygen API

​Example Agent Configuration

​Next Steps

​Reference