> ## Documentation Index
> Fetch the complete documentation index at: https://oxy.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# V0

# v0 Integration

Oxygen integrates with [v0.dev](https://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:

1. **Oxygen CLI**: Install the Oxygen CLI by following the [installation guide](../../README.md)
2. **v0 API Key**: Get your API key from [v0.dev/chat/settings/keys](https://v0.dev/chat/settings/keys)

## Configuration

### 1. Set up Environment Variable

Export your v0 API key as an environment variable:

```bash theme={null}
export V0_API_KEY="your-v0-api-key-here"
```

To persist this across terminal sessions, add it to your shell profile:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```yaml theme={null}
tools:
  - name: v0_app
    type: create_v0_app
```

You can see a complete example in [crates/app/demo\_project/v0.agent.yml](../../../crates/app/demo_project/v0.agent.yml).

## Running Oxygen with v0 Integration

### Quick Start

1. Set up environment variables:

```bash theme={null}
# 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"
```

2. Navigate to a project with v0-enabled agent configuration:

```bash theme={null}
cd crates/app/demo_project
```

3. Run the agent:

```bash theme={null}
# Using debug build (recommended for development)
cargo build
./target/debug/oxy agent run v0.agent.yml
```

4. 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 Oxygen SDK for querying

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

5. **App Generation**: v0 generates a React application with the Oxygen 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:

```yaml theme={null}
# 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:

```bash theme={null}
export V0_API_KEY="your-key"
```

Verify it's set:

```bash theme={null}
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](../../../crates/app/demo_project/v0.agent.yml#L108).

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

1. Check if OXY\_API\_URL is set:

   ```bash theme={null}
   echo $OXY_API_URL
   ```

2. For local development with Oxygen web app, ensure it matches where your web app is running:

   ```bash theme={null}
   # 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 Oxygen instance URL:

   ```bash theme={null}
   export OXY_API_URL="https://your-oxy-instance.com/api"
   ```

4. Make sure the Oxygen 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 Oxygen API (firewall, CORS, network access)

## Example Agent Configuration

Here's a minimal agent configuration with v0 integration:

```yaml theme={null}
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](../../../crates/app/demo_project/v0.agent.yml)
* Learn about [SQL execution and persistence](../sql-tools.md)
* Read about [agent configuration](../../agents/configuration.md)

## Reference

* [v0.dev Documentation](https://v0.dev/docs)
* [Oxygen SDK Documentation](../../sdk/overview.md)
* [Agent Tools Reference](../../agents/tools.md)