Bitterbot-AI/notte

Notte

Hosted browser infrastructure with a CLI that does three things the bundled browser tool and Firecrawl cannot:

1. Functions — deploy a browser automation script as a serverless, API-callable endpoint with built-in cron scheduling. The natural fit for crystallized skills and dream-engine cycles.
2. Vault-backed login — passwords auto-fill on matching URLs without ever entering the model's context.
3. Stealth sessions — residential proxies + inline captcha solving, for sites where the bundled Chromium gets locked out.

Functions — deploy a browser flow as a callable API

Crystallized skills and dream-cycle automations both want the same thing: a stable, repeatable browser action the agent can call by name on a schedule. Notte Functions is exactly that.

# 1. Capture an agent's run as deterministic Python (or hand-write it).
notte agents workflow-code   # exports the latest agent's steps as Python
notte sessions workflow-code # or export from a CLI session

# 2. Deploy the script as a Function (one-shot — no servers, no infra).
notte functions create --file workflow.py
# → returns function_id

# 3. Run on demand, or schedule.
notte functions run                                # one-off
notte functions schedule-set --cron "0 */2 * * *"  # every 2h, matches dream cycles
notte functions runs                               # invocation history
notte functions fork                               # version forward without losing the original

# 4. Or invoke via HTTP from anywhere (skill scripts, gateway hooks, channels).
curl -X POST https://api.notte.cc/functions/{function_id}/runs/start \
  -H "Authorization: Bearer $NOTTE_API_KEY" \
  -d '{"url":"https://example.com","query":"laptop"}'

Why this matters for Bitterbot:

• A crystallized skill that ends in "open this URL and grab the data" can be backed by a Function — fast, deterministic, no LLM tokens per execution.
• Function schedule-set aligns directly with dream-engine cron triggers (every 2h consolidation, daily syncs, hourly monitors).
• notte agents workflow-code is structurally the same pattern as Bitterbot's dream engine crystallizing execution paths — the agent figures out the steps, then the deterministic Function takes over for production.
• Functions auto-inherit Notte's session capabilities: vault credentials, stealth proxies, captcha solving — without re-deploying anything.

When to use Notte vs the bundled tools

| Need | Use | | ---------------------------------------------------------------------------- | --------------------------------------------------------- | | Open a tab, click around, take a snapshot | Bundled browser tool (src/browser/) | | Pull a single page through a stealth fetch | Firecrawl via web_fetch (docs/tools/firecrawl.md) | | Crystallize a recurring browser flow into a callable API endpoint | notte functions | | Schedule a browser flow on a cron (dream-cycle aligned) | notte functions schedule-set | | Run a multi-step task on an authenticated site | notte session | | Log in without exposing the password to the LLM | notte vault | | The bundled browser is being challenged with captcha / Cloudflare / DataDome | notte (--solve-captchas, --proxy) | | Need a residential / geo-located IP | notte | | Hand a browsing goal to an agent and get a structured answer | notte agents |

notte does not replace the bundled browser. It's the deployment + infrastructure layer for browser flows that need to outlive a single agent run.

Setup

# Install (handled by the install metadata above).
brew tap nottelabs/notte-cli https://github.com/nottelabs/notte-cli.git && brew install notte
# or:
go install github.com/nottelabs/notte-cli/cmd/notte@latest

# Authenticate. Stores the API key in the system keyring.
notte auth login
# or: export NOTTE_API_KEY=...

Quick start

notte sessions start --proxy --solve-captchas
notte page goto "https://news.ycombinator.com"
notte page observe
notte page scrape --instructions "Top 10 story titles, points, and URLs as JSON"
notte sessions stop -y

observe returns interactive element IDs (@B3, @I1, @L9). Use those with click / fill, or fall back to Playwright selectors (#submit, button:has-text('Submit')) — both are accepted.

Vault-backed login (the biggest UX win over the bundled browser)

docs/tools/browser-login.md recommends manual login because automated logins trigger anti-bot defenses and can lock the account. Notte fixes this: store credentials in a vault and the browser auto-fills on matching URLs. The agent never sees the password.

notte vaults create --name "myservice"
notte vaults credentials add --vault-id <vault-id> \
  --url "https://myservice.com" \
  --email "[email protected]" \
  --password "..." \
  --mfa-secret "<TOTP_BASE32_SECRET>"   # optional TOTP

notte sessions start
notte page goto "https://myservice.com/login"
# Credentials auto-fill from the matching vault entry.

This unblocks autonomous flows during dream cycles where there's no user available to log in manually.

Agent runtime (delegate the whole task)

For multi-step goals, hand the task to a Notte agent:

notte agents start --task "Find the cheapest non-stop SFO→CDG flight on Sep 14 and return the URL"
notte agents status
notte agents replay     # session recording / step trace

Agents are cheaper than authoring step-by-step CLI calls when the task has many branches.

Stealth flags worth knowing

| Flag | Effect | | --------------------- | ------------------------------------------------------ | | --proxy | Route through Notte's residential proxy pool | | --proxy-country <c> | ISO country code (us, gb, fr, de, …) | | --solve-captchas | Auto-solve reCAPTCHA / hCaptcha / Cloudflare turnstile | | --user-agent <ua> | Pin a specific UA string | | --cdp-url <url> | Bring-your-own remote browser (e.g. Lightpanda) | | --headless=false | Required when --cdp-url points to Lightpanda Cloud |

Page actions (cheat sheet)

notte page click "@B3" | "#submit-button"
notte page fill "@I1" "hello"        # add --enter to submit
notte page check "#tos"
notte page select "#country" "France"
notte page upload "#file" --file ./report.pdf
notte page download "@L5"
notte page eval-js 'document.title'
notte page screenshot
notte page wait 500
notte page press "Enter" | "Escape" | "Tab"
notte page scroll-down [px] | scroll-up [px]

Navigation: goto, back, forward, reload, new-tab, switch-tab, close-tab.

Structured extraction

notte page scrape --instructions "Every job posting: title, company, location, salary range" -o json
notte page scrape --instructions "Article body and author" --only-main-content

Note: for routine single-page extraction without auth or anti-bot needs, web_fetch (with Firecrawl) is the lighter path. Use notte page scrape when extraction lives behind login or after a multi-step navigation.

MCP path (no install required)

Notte ships an MCP server (notte-mcp). It can be called through the existing mcporter skill without installing the Notte CLI:

NOTTE_API_KEY=... mcporter call --stdio "uv run --with notte-mcp python -m notte_mcp.server" \
  notte_scrape url=https://example.com instructions="Extract pricing tiers"

Use the CLI by default — the MCP path is mainly useful inside flows already orchestrating MCP calls.

Live viewer (debugging)

notte sessions start -o json | jq -r '.viewer_url'
# or
notte sessions viewer

Environment variables

| Variable | Purpose | | --------------------------- | ------------------------------------------- | | NOTTE_API_KEY | API key (alternative to notte auth login) | | NOTTE_SESSION_ID | Default session for page commands | | NOTTE_API_URL | Override API endpoint | | NOTTE_MCP_SERVER_PROTOCOL | stdio or sse (only for the MCP server) |

Tips

• Always observe before click / fill / scrape. Element IDs come from observe output.
• After every navigation, observe again — IDs are scoped to the current DOM snapshot.
• Stop sessions you start. notte sessions stop -y skips the prompt. Idle sessions cost API budget.
• Lightpanda + --cdp-url requires --headless=false. Otherwise the CDP server returns 500.
• @B3 clicking the wrong element? Fall back to a Playwright selector.
• Modals blocking clicks? notte page press "Escape" then notte page wait 500.

Troubleshooting

| Symptom | Fix | | ----------------------------------- | ------------------------------------------------------------ | | Site keeps blocking / shows captcha | Restart with --proxy --solve-captchas | | Empty / partial scrape | Add notte page wait 1000 then re-observe before scrape | | @B3 clicks the wrong thing | Use a Playwright selector (button:has-text('Submit')) | | Lightpanda CDP returns 500 | Add --headless=false to sessions start | | Agent stuck on a captcha | Stop session, restart with --solve-captchas | | 401 / auth errors | Re-run notte auth login or set NOTTE_API_KEY |