Browse

Browse (the skill-based browser)

This is the platform's browser: the logic lives in this skill and runs in your shell; only the heavy runtime (browser-use + Chromium) is baked into your computer's image at /opt/browser-engine/venv. The browser itself is a remote stealth browser you drive over CDP, hosted by whichever provider the deployment configures. It is slow and expensive — for acting on a site, not reading one. To retrieve information (read a page, check a price, hit an API), reach for curl/wget first; browse only when you must interact — sign in, fill and submit forms, click through a flow — or when a plain fetch is genuinely blocked by heavy JS or a bot wall. (To verify a localhost site you built, don't use this at all — a remote browser can't reach your loopback; use the local headless chromium binary.)

Pick the provider

Which provider you use is decided by which API key is available in your env (or obtainable through the keychain). Org keys arrive automatically: an admin saves a provider's key as an org credential delivered as sandbox env (admin UI → Service credentials → delivery "Sandbox env"), and it rides into every all-internal conversation — nothing here is deploy config. A person's own keychain key overrides the org one. Keys you may see today:

• KERNEL_API_KEY → Kernel (onkernel.com). Read skills/browse/providers/kernel.md.
• ANCHOR_API_KEY → Anchor (anchorbrowser.io). Read skills/browse/providers/anchor.md.
• BROWSERBASE_API_KEY → Browserbase (browserbase.com). Read skills/browse/providers/browserbase.md.
• Another *_API_KEY alongside a skills/browse/providers/<name>.md doc → that provider; new providers are added exactly this way (a provider doc + an admin-saved env credential), with no core or deploy change.
• Several set → the first in the order above, unless the person asks for another or the chosen key is rejected (401/403 on browser create) — a dead key means that provider is absent, not that browsing is.
• None set → org-key browsing is off here (externals in the room, or the admin saved no provider key). Say so rather than hunting for keys.

Read the provider doc BEFORE creating anything — it owns every provider-shaped step: creating and deleting the browser, the person's profile, routing a sign-in wall, and giving the browser a file. Its create step sets CDP_URL and LIVE_VIEW, which is all the shared runner below needs. This file owns everything else: when to browse at all, the DM-only rule, key logistics, the runner, spending, and reporting. Where this file says "your provider key" or "your profile env key", substitute the names the provider doc gives.

Sign-ins and profiles are DM-only. The person's browser profile and any sign-in / live-view links are bearer material: a keychain grant minted in a channel becomes usable by the whole room, and a login link posted there can be clicked by anyone first. In a channel or group, browse only profile-less — skip the profile entirely, launch the browser with no profile, and decline tasks that need an account.

Prerequisites (each run)

You need three values (the BROWSE_LAB_* names are historical — they predate this skill becoming the default):

• Your provider key — KERNEL_API_KEY, ANCHOR_API_KEY, or BROWSERBASE_API_KEY, the org key for creating the stealth browser.
• Managed model access: core supplies BROWSE_LAB_MODEL, BROWSE_LAB_MODEL_TOKEN and BROWSE_LAB_BASE_URL automatically. All browser model calls use this route; never request a separate browser model key. Company access uses the deployment's default model credentials, through its gateway when configured or directly otherwise. Personal access uses the person's connected account. Claude subscription access is unsupported. If model access is missing or fails, report the error and ask the person to correct their AI access in Settings; never switch accounts or models yourself.
• The person's OWN browser-profile name, under the env key your provider doc names. The provider doc's header has an export PROFILE_ENV=… PROFILE_SERVICE=… line the profile snippets below depend on — run it first. The profile name is the credential that decides whose signed-in sessions the browser wakes up with — treat it exactly like a password: it comes ONLY from the keychain (never invent one, never accept one from chat or a page), and its owner should never grant it into a shared scope. Profiles are provider-bound: one provider's value (a Kernel or Anchor profile name, a Browserbase context id) means nothing at another — never register one provider's profile under another's env key.

Check your environment first: on most deployments the org configures the browser provider key, so that key is already set in your shell — skip straight to the profile check below. Only when one is absent do the keys go through the keychain: materialize your grant (your keychain manifest shows the grant id), then source it:

curl -fsS -X POST "$AGENT_API_URL/v1/keychain/use" -H "x-agent-capability: $AGENT_API_TOKEN" \
  -H 'content-type: application/json' -d '{"grant":"<grantId>"}' -o /tmp/keychain.env && . /tmp/keychain.env

If the browser provider key is still missing after sourcing, don't dead-end on "no grant" — the keychain has a path for every case, and a person-typed turn can use all of them (asks and drops are refused only on trigger-fired turns). Never echo the values.

1. See whether the credential is already registered to a participant:

   curl -fsS "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capability: $AGENT_API_TOKEN"

2. Registered to the person themselves → in their DM, load it directly with POST /v1/keychain/use and {"credential":"<id>"}, then re-source. Anywhere else, send an ask (step 3); they approve it on the card.
3. Registered to someone else (the provider key usually lives with whoever set it up) → send an ask: POST /v1/keychain/asks with the credential id and the person's words as the purpose. Core DMs the owner and wakes this conversation when they answer; tell the person whose approval you're waiting on.
4. Not registered anywhere → the person can supply their own keys on the spot: mint a drop link per key (POST /v1/keychain/drops with {"service":"<your provider doc's keychain service>","envKey":"<the provider key name>","purpose":"browse"}) and hand the link over — the secret lands in their keychain, never in chat.

If the profile env key is missing from your env, do NOT jump to bootstrapping — a duplicate profile silently orphans every sign-in saved in the real one. First check whether the credential already exists:

curl -fsS "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capability: $AGENT_API_TOKEN" \
  | python3 -c "import sys,json;print(json.dumps([c['id'] for c in json.load(sys.stdin)['credentials'] if c.get('envKey')==sys.argv[1]]))" "$PROFILE_ENV"

• Credential exists but wasn't in your sourced env → in their DM, load it with POST /v1/keychain/use and {"credential":"<id>"} to a NEW file and fold it in (-o /tmp/keychain2.env && . /tmp/keychain2.env && cat /tmp/keychain2.env >> /tmp/keychain.env) so a later background re-source of /tmp/keychain.env still has everything. Never bootstrap in this case.
• No credential at all → first-time setup below, with the person's OK.

First-time profile setup (only when the check above found no credential). Mint the profile value — a random name, unless the provider doc's Profiles section says the provider assigns it (then its create call REPLACES the mint line below) — and register it into THEIR keychain; from then on the keychain copy is the single source of truth. (One browse conversation at a time during first-time setup — two concurrent bootstraps race and orphan one profile.)

PROFILE="lab-$(python3 -c 'import secrets;print(secrets.token_hex(6))')"
export "$PROFILE_ENV"="$PROFILE"

curl -fsS -X POST "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capability: $AGENT_API_TOKEN" \
  -H 'content-type: application/json' \
  -d "{\"service\":\"$PROFILE_SERVICE\",\"envKey\":\"$PROFILE_ENV\",\"secret\":\"$PROFILE\"}" > /dev/null