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

# Cookbook

> Runnable browser examples grouped by use case. Each one is self-contained: paste it, run it, read the output.

<Info>
  Every example is a single self-contained file in the [Box SDK
  repo](https://github.com/upstash/box/tree/main/packages/sdk/examples/browser).
  All of them need `UPSTASH_BOX_API_KEY`. Examples marked **AI** use metered
  browser AI (`act`, `extract`, `observe`) and need a model provider key on the box
  or account. Everything else runs with the Box key alone.
</Info>

## Agentic browsing

Goal-driven browsing: hand a goal to the box's agent, or drive your own loop.

<CardGroup cols={2}>
  <Card title="In-box agent" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/agentic/01-in-box-agent.ts">
    Hand a goal to `box.agent.run`; the box's agent drives the browser through the chrome-devtools MCP and writes results to the box (needs an agent key; bills coding-agent tokens). **Agent**
  </Card>

  <Card title="Build your own loop" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/agentic/02-build-your-own-loop.ts">
    A live `observe` then `act(action)` then `extract` loop you own, with `extract` as the stop check. **AI**
  </Card>
</CardGroup>

## Automation

Forms, files, and durable sessions.

<CardGroup cols={2}>
  <Card title="Checkout with one AI step" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/automation/01-checkout-with-one-ai-step.ts">
    Script the deterministic steps, delegate the judgment call to a single `act`, and assert the result.
  </Card>

  <Card title="Download and process" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/automation/02-download-and-process.ts">
    A download lands on the box filesystem and is processed in place.
  </Card>

  <Card title="Upload from box" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/automation/03-upload-from-box.ts">
    Upload a box-generated file through a real form over CDP.
  </Card>

  <Card title="Log in once, reuse session" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/automation/04a-login-once-keep-alive.ts">
    Log in once into a keep-alive box, then have any later script reuse the session.
  </Card>
</CardGroup>

## Retrieval

Structured data out of rendered pages.

<CardGroup cols={2}>
  <Card title="Catalog extraction" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/retrieval/01-catalog-extraction.ts">
    One `extract` call, schema-validated typed output, screenshot provenance. **AI**
  </Card>

  <Card title="AI-compiled scraper" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/retrieval/02-ai-compiled-scraper.ts">
    AI compiles selectors once, then every later run scrapes deterministically. **AI (first run only)**
  </Card>

  <Card title="Crawl to dataset" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/retrieval/03-crawl-to-dataset.ts">
    Crawl a client-rendered docs section into chunked JSONL via `tab.content()`.
  </Card>

  <Card title="Evidence pack" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/retrieval/04-evidence-pack.ts">
    Full-page captures plus a hashed manifest, assembled in the box and downloaded as one archive.
  </Card>
</CardGroup>

## Testing

The box as a test environment.

<CardGroup cols={2}>
  <Card title="Playwright migration" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/testing/01-playwright-migration.ts">
    An existing Playwright test where only the launch line changes.
  </Card>

  <Card title="Test your own app" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/testing/02-test-your-own-app.ts">
    The box hosts the app under test and browses it on its own localhost.
  </Card>

  <Card title="Visual regression" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/testing/04-visual-regression.ts">
    Pixelmatch diffs against baselines stored on the box.
  </Card>
</CardGroup>