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

# Deploy Web App

> Deploy the web terminal to Vercel

The ouroborai web terminal is a Next.js 15 application with a chat-based
interface, session management, and real-time position tracking. This guide
covers deploying it to Vercel.

## Prerequisites

* A [Vercel](https://vercel.com) account
* The ouroborai monorepo cloned locally
* A running API server (see [Deploy API Server](/docs/guides/deploy-api))
* A Dynamic environment ID for wallet connection

## Deployment

<Steps>
  <Step title="Import the project on Vercel">
    In the Vercel dashboard, click **Add New Project** and import the ouroborai
    GitHub repository. Set the **Root Directory** to `apps/web` so Vercel
    detects the Next.js configuration correctly.

    Alternatively, use the Vercel CLI:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    cd apps/web
    npx vercel
    ```
  </Step>

  <Step title="Configure environment variables">
    In the Vercel project settings, navigate to **Environment Variables** and
    add:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    NEXT_PUBLIC_API_URL=https://your-api.railway.app
    NEXT_PUBLIC_DYNAMIC_ENV_ID=your_dynamic_environment_id
    ```

    <Note>
      `NEXT_PUBLIC_API_URL` must point to your deployed API server. The web
      terminal calls this URL for agent prompts, portfolio data, market prices,
      and all other backend operations.
    </Note>

    Both variables use the `NEXT_PUBLIC_` prefix because they are accessed in
    client-side code (React hooks that call `fetch` directly from the browser).
  </Step>

  <Step title="Configure the framework preset">
    Vercel auto-detects Next.js. Confirm these build settings:

    | Setting          | Value                             |
    | ---------------- | --------------------------------- |
    | Framework Preset | Next.js                           |
    | Build Command    | `bun run build` (or `next build`) |
    | Output Directory | `.next`                           |
    | Install Command  | `bun install`                     |
    | Node.js Version  | 20.x                              |
  </Step>

  <Step title="Deploy">
    Push to your connected branch or trigger a deploy from the dashboard. Vercel
    builds the Next.js app and deploys it to its edge network.

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    npx vercel --prod
    ```
  </Step>

  <Step title="Set up a custom domain (optional)">
    In the Vercel project settings, navigate to **Domains** and add your custom
    domain (e.g., `app.ouroborai.com`).

    Update your DNS provider with the CNAME record Vercel provides. Once DNS
    propagates, Vercel provisions an SSL certificate automatically.

    Remember to update `CORS_ORIGIN` on your API server to include the new
    domain:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    CORS_ORIGIN=https://app.ouroborai.com,https://ouroborai.com
    ```
  </Step>

  <Step title="Verify the deployment">
    Open the deployed URL in your browser. You should see the terminal
    interface with:

    * A chat panel in the center for agent interaction
    * A left sidebar with session tabs and activity feed
    * A right sidebar with wallet balances, positions, and market data

    Try sending a prompt like "What tokens can I trade?" to verify the API
    connection is working.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="TypeScript build errors">
    The web app imports types inline to avoid pulling in the full `@arb-agent/sdk`
    barrel (which includes Node.js-only modules like `ArbWallet`). If you see
    type errors during build, ensure:

    * You are building from the `apps/web` root directory
    * The `tsconfig.json` in `apps/web` has `"strict": true`
    * No server-only SDK imports have leaked into client components

    Run a local build to debug before deploying:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    cd apps/web
    bun run build
    ```
  </Accordion>

  <Accordion title="Wallet connectivity issues">
    The web terminal uses Dynamic for wallet connection. If wallets fail to
    connect:

    * Verify `NEXT_PUBLIC_DYNAMIC_ENV_ID` is set correctly
    * Check that the Dynamic dashboard has Arbitrum One (chain 42161) enabled
    * Ensure your domain is allowed in the Dynamic CORS settings
  </Accordion>

  <Accordion title="API requests returning CORS errors">
    The API server must include the web app's domain in `CORS_ORIGIN`. The
    server allows these headers: `Content-Type`, `X-PAYMENT`, and
    `Authorization`. If you see CORS errors:

    * Update `CORS_ORIGIN` on the API server to include your Vercel URL
    * Separate multiple origins with commas (no spaces)
    * Redeploy the API server after changing the variable
  </Accordion>

  <Accordion title="Blank page after deployment">
    This usually indicates `NEXT_PUBLIC_API_URL` is missing or incorrect. Open
    the browser developer console and check for network errors. The web app
    expects the API to be reachable at the configured URL.
  </Accordion>
</AccordionGroup>