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

# Quick Start

> Get ouroborai running locally in 5 minutes

This guide walks you through cloning the repository, configuring credentials,
starting the API server, and submitting your first agent prompt.

## Prerequisites

Before you begin, make sure you have:

* **Bun v1.0+** -- install from [bun.sh](https://bun.sh) if needed
* **Arbitrum RPC URL** -- a standard JSON-RPC endpoint from Alchemy, Infura,
  or any Arbitrum One provider
* **Anthropic API key** -- required for the Claude-backed agent runner
* **Funded wallet** -- an Arbitrum One wallet with ETH for gas and USDC for
  x402 payments

<Note>
  You can use Arbitrum Sepolia for testing. Replace the RPC URL and contract
  addresses accordingly.
</Note>

## Setup

<Steps>
  <Step title="Clone and install">
    Clone the monorepo and install all workspace dependencies with Bun.

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    git clone https://github.com/ouroborai-labs/agent.git
    cd agent
    bun install
    ```

    This installs dependencies for all packages (`sdk`, `adapters`,
    `timeboost`, `smart-account`) and apps (`api`, `web`, `telegram`,
    `mcp-server`).
  </Step>

  <Step title="Configure environment variables">
    Create an `.env` file inside `apps/api/`:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    cp apps/api/.env.example apps/api/.env
    ```

    Open `apps/api/.env` and fill in the required values:

    <CodeGroup>
      ```bash .env (required) theme={"theme":{"light":"dracula","dark":"dracula"}}
      # Wallet private key (for smart account signer)
      PRIVATE_KEY=0xYOUR_PRIVATE_KEY

      # Anthropic API key (powers the agent runner)
      ANTHROPIC_API_KEY=sk-ant-...

      # Arbitrum One RPC
      ARB_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY
      ```

      ```bash .env (optional) theme={"theme":{"light":"dracula","dark":"dracula"}}
      # Redis URL -- enables persistent job queue, thread store, and nonce tracking
      # Falls back to in-memory stores when omitted
      REDIS_URL=redis://localhost:6379

      # Port for the Hono API server (default: 3000)
      PORT=3000
      ```
    </CodeGroup>

    <Warning>
      Never commit your `.env` file. It contains your private key and API
      credentials. The repository `.gitignore` already excludes it.
    </Warning>
  </Step>

  <Step title="Start the API server">
    Launch the development server:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    bun run dev
    ```

    You should see output indicating the Hono server is listening:

    ```
    ouroborai API listening on http://localhost:3000
    ```
  </Step>

  <Step title="Verify the server is running">
    In a new terminal, hit the health endpoint:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    curl http://localhost:3000/health
    ```

    Expected response:

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    { "status": "ok" }
    ```
  </Step>

  <Step title="Submit your first prompt">
    Send a natural language prompt to the agent:

    <CodeGroup>
      ```bash curl theme={"theme":{"light":"dracula","dark":"dracula"}}
      curl -X POST http://localhost:3000/agent/prompt \
        -H "Content-Type: application/json" \
        -d '{"prompt": "What tokens can I trade on Uniswap?"}'
      ```

      ```typescript fetch theme={"theme":{"light":"dracula","dark":"dracula"}}
      const response = await fetch("http://localhost:3000/agent/prompt", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          prompt: "What tokens can I trade on Uniswap?",
        }),
      });

      const data = await response.json();
      console.log(data);
      ```
    </CodeGroup>

    The response includes a `jobId` you can poll for the agent's answer:

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    { "jobId": "job_abc123", "threadId": "thread_xyz789" }
    ```

    Check the result:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    curl http://localhost:3000/agent/job/job_abc123
    ```
  </Step>

  <Step title="Continue the conversation">
    Pass the `threadId` from the previous response to maintain context across
    turns:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    curl -X POST http://localhost:3000/agent/prompt \
      -H "Content-Type: application/json" \
      -d '{
        "prompt": "Swap 50 USDC for ARB",
        "threadId": "thread_xyz789"
      }'
    ```

    The agent remembers the prior conversation and executes against the
    same session state.
  </Step>
</Steps>

## Optional: Start the Web Terminal

The web UI provides a chat-based terminal interface with session management,
activity feeds, and position tracking.

```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
cd apps/web
bun run dev
```

Open [http://localhost:3001](http://localhost:3001) in your browser.

## Optional: Start the Telegram Bot

```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
cd apps/telegram
TELEGRAM_BOT_TOKEN=your_bot_token bun run dev
```

Send `/trade 50 USDC for ARB` to your bot to test.

## What's Next

<CardGroup cols={2}>
  <Card title="Architecture" icon="sitemap" href="/docs/getting-started/architecture">
    Understand how requests flow from prompt to on-chain execution.
  </Card>

  <Card title="x402 Payments" icon="credit-card" href="/docs/agent-api/x402-payments">
    Learn how the micropayment protocol works for production use.
  </Card>

  <Card title="Trading" icon="arrow-right-arrow-left" href="/docs/features/trading">
    Explore spot trading capabilities on Uniswap V3.
  </Card>

  <Card title="Add a Skill" icon="puzzle-piece" href="/docs/guides/add-a-skill">
    Extend the agent with your own protocol integration.
  </Card>
</CardGroup>