> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/jo-inc/camofox-browser/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get a working browser automation example in under 2 minutes

## Prerequisites

Before starting, ensure you have:

* **Node.js 18+** installed
* **\~500MB disk space** for Camoufox browser download (happens on first run)
* **curl** or any HTTP client for testing

<Note>
  Camoufox downloads automatically on first launch (\~300MB). This is a one-time download that's cached locally.
</Note>

## Start the server

<Steps>
  <Step title="Clone and install">
    Clone the repository and install dependencies:

    <CodeGroup>
      ```bash npm theme={null}
      git clone https://github.com/jo-inc/camofox-browser
      cd camofox-browser
      npm install
      ```

      ```bash yarn theme={null}
      git clone https://github.com/jo-inc/camofox-browser
      cd camofox-browser
      yarn install
      ```

      ```bash pnpm theme={null}
      git clone https://github.com/jo-inc/camofox-browser
      cd camofox-browser
      pnpm install
      ```
    </CodeGroup>
  </Step>

  <Step title="Launch the server">
    Start the Camofox server:

    ```bash theme={null}
    npm start
    ```

    You'll see output like:

    ```json theme={null}
    {"ts":"2026-02-28T10:15:30.123Z","level":"info","msg":"server listening","port":9377}
    ```

    The server runs on **port 9377** by default. Change with `CAMOFOX_PORT=8080 npm start`.

    <Info>
      On first run, Camoufox will download the browser engine (\~300MB). This takes 1-2 minutes depending on your connection.
    </Info>
  </Step>

  <Step title="Verify it's running">
    Check the health endpoint:

    ```bash theme={null}
    curl http://localhost:9377/health
    ```

    Response:

    ```json theme={null}
    {
      "ok": true,
      "engine": "camoufox",
      "browserConnected": false,
      "browserRunning": false,
      "activeTabs": 0,
      "consecutiveFailures": 0
    }
    ```

    <Note>
      `browserRunning: false` is normal - the browser launches lazily on first tab creation to save resources.
    </Note>
  </Step>
</Steps>

## Your first automation

Let's navigate to a website, get its content, and interact with an element.

<Steps>
  <Step title="Create a tab">
    Create a new browser tab:

    ```bash theme={null}
    curl -X POST http://localhost:9377/tabs \
      -H 'Content-Type: application/json' \
      -d '{
        "userId": "agent1",
        "sessionKey": "task1",
        "url": "https://example.com"
      }'
    ```

    Response:

    ```json theme={null}
    {
      "tabId": "3f8a9b2c-1d4e-4f5a-8b9c-2d3e4f5a6b7c",
      "url": "https://example.com/"
    }
    ```

    Save the `tabId` - you'll need it for subsequent requests.

    <Info>
      * `userId`: Isolates cookies/storage between users (multi-tenant support)
      * `sessionKey`: Groups tabs by conversation or task
    </Info>
  </Step>

  <Step title="Get page snapshot">
    Get an accessibility snapshot with element refs:

    ```bash theme={null}
    curl "http://localhost:9377/tabs/3f8a9b2c-1d4e-4f5a-8b9c-2d3e4f5a6b7c/snapshot?userId=agent1"
    ```

    Response:

    ```json theme={null}
    {
      "url": "https://example.com/",
      "snapshot": "- heading \"Example Domain\"\n  - paragraph \"This domain is for use in illustrative examples in documents.\"\n  - link \"More information...\" [e1]\n",
      "refsCount": 1,
      "truncated": false,
      "totalChars": 156,
      "hasMore": false,
      "nextOffset": null
    }
    ```

    The `snapshot` field contains the accessibility tree with element refs (`e1`, `e2`, etc.).

    <Tip>
      Accessibility snapshots are \~90% smaller than raw HTML, saving context window tokens.
    </Tip>
  </Step>

  <Step title="Interact with an element">
    Click the link using its ref `e1`:

    ```bash theme={null}
    curl -X POST http://localhost:9377/tabs/3f8a9b2c-1d4e-4f5a-8b9c-2d3e4f5a6b7c/click \
      -H 'Content-Type: application/json' \
      -d '{
        "userId": "agent1",
        "ref": "e1"
      }'
    ```

    Response:

    ```json theme={null}
    {
      "ok": true,
      "url": "https://www.iana.org/domains/reserved",
      "refsAvailable": true
    }
    ```

    The browser navigated to the link's target! Notice `refsAvailable: true` - refs are automatically rebuilt after navigation.
  </Step>

  <Step title="Try a search macro">
    Navigate using a search macro:

    ```bash theme={null}
    curl -X POST http://localhost:9377/tabs/3f8a9b2c-1d4e-4f5a-8b9c-2d3e4f5a6b7c/navigate \
      -H 'Content-Type: application/json' \
      -d '{
        "userId": "agent1",
        "macro": "@google_search",
        "query": "best coffee beans 2026"
      }'
    ```

    Response:

    ```json theme={null}
    {
      "ok": true,
      "tabId": "3f8a9b2c-1d4e-4f5a-8b9c-2d3e4f5a6b7c",
      "url": "https://www.google.com/search?q=best+coffee+beans+2026",
      "refsAvailable": true
    }
    ```

    Search macros expand to full URLs automatically. Available macros:

    * `@google_search`
    * `@youtube_search`
    * `@amazon_search`
    * `@reddit_search`
    * `@wikipedia_search`
    * `@twitter_search`
    * And 8 more!
  </Step>
</Steps>

## Type into a form

Let's search Google by typing into the search box:

<CodeGroup>
  ```bash Navigate to Google theme={null}
  curl -X POST http://localhost:9377/tabs/YOUR_TAB_ID/navigate \
    -H 'Content-Type: application/json' \
    -d '{
      "userId": "agent1",
      "url": "https://www.google.com"
    }'
  ```

  ```bash Get snapshot to find search box theme={null}
  curl "http://localhost:9377/tabs/YOUR_TAB_ID/snapshot?userId=agent1"
  # Look for: [searchbox e5] Search
  ```

  ```bash Type into search box theme={null}
  curl -X POST http://localhost:9377/tabs/YOUR_TAB_ID/type \
    -H 'Content-Type: application/json' \
    -d '{
      "userId": "agent1",
      "ref": "e5",
      "text": "weather today"
    }'
  ```

  ```bash Press Enter to submit theme={null}
  curl -X POST http://localhost:9377/tabs/YOUR_TAB_ID/press \
    -H 'Content-Type: application/json' \
    -d '{
      "userId": "agent1",
      "key": "Enter"
    }'
  ```
</CodeGroup>

<Warning>
  Element refs reset after navigation. Always get a fresh snapshot after clicking links or submitting forms.
</Warning>

## Scroll and get more content

For long pages, scroll down to load more content:

```bash theme={null}
curl -X POST http://localhost:9377/tabs/YOUR_TAB_ID/scroll \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "agent1",
    "direction": "down",
    "amount": 1000
  }'
```

Then get a fresh snapshot:

```bash theme={null}
curl "http://localhost:9377/tabs/YOUR_TAB_ID/snapshot?userId=agent1"
```

## Close the tab

When done, close the tab:

```bash theme={null}
curl -X DELETE "http://localhost:9377/tabs/YOUR_TAB_ID?userId=agent1"
```

Response:

```json theme={null}
{"ok": true}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Learn about Docker, Fly.io deployment, and OpenClaw plugin setup
  </Card>

  <Card title="API reference" icon="code" href="/api/tabs/create">
    Explore all available endpoints and parameters
  </Card>

  <Card title="Search macros" icon="magnifying-glass" href="/concepts/search-macros">
    See all 14 built-in search shortcuts
  </Card>

  <Card title="Cookie import" icon="cookie" href="/guides/cookie-import">
    Import cookies for authenticated browsing (LinkedIn, Amazon, etc.)
  </Card>
</CardGroup>

## Common workflows

<AccordionGroup>
  <Accordion title="Get all links on a page">
    ```bash theme={null}
    curl "http://localhost:9377/tabs/YOUR_TAB_ID/links?userId=agent1&limit=50"
    ```

    Returns an array of `{url, text}` objects.
  </Accordion>

  <Accordion title="Take a screenshot">
    ```bash theme={null}
    curl "http://localhost:9377/tabs/YOUR_TAB_ID/screenshot?userId=agent1" \
      -o screenshot.png
    ```

    Returns a PNG image.
  </Accordion>

  <Accordion title="Navigate with browser buttons">
    ```bash Back button theme={null}
    curl -X POST http://localhost:9377/tabs/YOUR_TAB_ID/back \
      -H 'Content-Type: application/json' \
      -d '{"userId": "agent1"}'
    ```

    ```bash Forward button theme={null}
    curl -X POST http://localhost:9377/tabs/YOUR_TAB_ID/forward \
      -H 'Content-Type: application/json' \
      -d '{"userId": "agent1"}'
    ```

    ```bash Refresh page theme={null}
    curl -X POST http://localhost:9377/tabs/YOUR_TAB_ID/refresh \
      -H 'Content-Type: application/json' \
      -d '{"userId": "agent1"}'
    ```
  </Accordion>

  <Accordion title="Close all tabs for a user">
    ```bash theme={null}
    curl -X DELETE http://localhost:9377/sessions/agent1
    ```

    Closes all tabs and deletes all cookies/storage for `agent1`.
  </Accordion>
</AccordionGroup>