Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

Add Browser Use Cloud provider to the browse skill (#2367)

Joshua France161adeef5f58
diff --git a/docs/model-gateway.md b/docs/model-gateway.md
index b4f6ee467..4990c8c19 100644
--- a/docs/model-gateway.md
+++ b/docs/model-gateway.md
@@ -24,7 +24,7 @@ credentials when no gateway is configured; ChatGPT access uses the user's connec
OpenAI account, including refreshed subscription access; Claude access supports
API keys. Claude subscription access is unavailable for the inner browser agent
and returns an actionable error. No account silently falls back to another.
-Kernel, Anchor and Browserbase still use their own credentials for browser sessions.
+Kernel, Anchor, Browserbase and Browser Use still use their own credentials for browser sessions.
Core gives internal, non-strict turns a one-hour capability bound to the account,
model and conversation scope. The sandbox sends OpenAI-compatible, non-streaming
diff --git a/skills-seed/browse/SKILL.md b/skills-seed/browse/SKILL.md
index cab1a73cd..b41b1dd99 100644
--- a/skills-seed/browse/SKILL.md
+++ b/skills-seed/browse/SKILL.md
@@ -1,6 +1,6 @@
---
name: browse
-description: Drive a real stealth browser from your shell — act on websites (order food, file an expense, pull data behind a login), with per-person persistent sign-ins via the provider's managed auth (Kernel, Anchor, or Browserbase — picked by which API key you have). Use for ACTING on a site; to just read a page, use curl/wget first. Requires managed model access and a keychain grant for the browser provider key; follow the missing-key steps below.
+description: Drive a real stealth browser from your shell — act on websites (order food, file an expense, pull data behind a login), with per-person persistent sign-ins kept in the person's browser profile (Kernel, Anchor, Browserbase, or Browser Use — picked by which API key you have). Use for ACTING on a site; to just read a page, use curl/wget first. Requires managed model access and a keychain grant for the browser provider key; follow the missing-key steps below.
---
# Browse (the skill-based browser)
@@ -31,6 +31,8 @@ in this flow, including the runner.
- `ANCHOR_API_KEY` → **Anchor** (anchorbrowser.io). Read `providers/anchor.md`.
- `BROWSERBASE_API_KEY` → **Browserbase** (browserbase.com). Read
`providers/browserbase.md`.
+- `BROWSER_USE_API_KEY` → **Browser Use Cloud** (browser-use.com). Read
+ `providers/browser-use.md`.
- Another `*_API_KEY` alongside a `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.
@@ -58,7 +60,8 @@ profile, and decline tasks that need an account.
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
+- Your provider key — `KERNEL_API_KEY`, `ANCHOR_API_KEY`, `BROWSERBASE_API_KEY`, or
+ `BROWSER_USE_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;
@@ -73,7 +76,7 @@ becoming the default):
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
+ one provider's value (a Kernel or Anchor profile name, a Browserbase context id, a Browser Use profile 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,
@@ -253,12 +256,34 @@ The last stdout line is the typed outcome:
a domain the task didn't name). Then follow your provider doc's "Routing a sign-in wall"
section — every provider
flow ends the same way: the person signs in once, the sign-in lands durably in THEIR
- profile (or the provider's managed store), and you relaunch the browser and re-run the
- task. Two rules hold for all providers: sign-in and live-view links are single-audience
+ profile, and you relaunch the browser and re-run the
+ task. (Where the write-back happens differs — Kernel and Browser Use save from the task
+ browser itself, on delete or stop; Browserbase and Anchor save only from a dedicated
+ sign-in session — the provider doc says which its flow uses.) Two rules hold for all
+ providers: sign-in and live-view links are single-audience
bearer material — hand them to the person in a DM, never open them yourself; and a
mid-session verification check (already signed in, then challenged) is cleared on the LIVE
browser — hand the person `$LIVE_VIEW`, wait for done, re-run.
+Steering the live browser to the wall is one shared script, written once per session (the
+provider doc says which CDP websocket to pass):
+
+```bash
+cat > /tmp/browse-nav.py <<'PY'
+import os
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+ b = p.chromium.connect_over_cdp(os.environ["CDP_URL"])
+ ctx = b.contexts[0]
+ page = ctx.pages[0] if ctx.pages else ctx.new_page()
+ page.goto(open("/tmp/wall-url.txt").read().strip(), timeout=60000)
+ b.close()
+PY
+```
+
+It drives the browser's existing context (`contexts[0]`) — a fresh context doesn't carry
+the profile — and closing the CDP connection afterwards stops no browser and saves nothing.
+
## 3. Clean up
Always delete the browser when the task is over (it otherwise idles until its timeout) —
diff --git a/skills-seed/browse/providers/browser-use.md b/skills-seed/browse/providers/browser-use.md
new file mode 100644
index 000000000..71023fb73
--- /dev/null
+++ b/skills-seed/browse/providers/browser-use.md
@@ -0,0 +1,185 @@
+# Browse provider: Browser Use Cloud (browser-use.com)
+
+Provider names for the shared flow in SKILL.md: API key `BROWSER_USE_API_KEY`, keychain
+service `browser-use`. Run this before the shared profile snippets:
+
+```bash
+export PROFILE_ENV=BROWSER_USE_PROFILE PROFILE_SERVICE=browser-use-profile
+```
+
+All calls go to `https://api.browser-use.com/api/v4` and authenticate with the
+`X-Browser-Use-API-Key` header (no `Bearer` prefix). Credits, concurrency and the key's
+project are at `GET https://api.browser-use.com/api/v2/billing/account` — check it first
+when a create returns 402 (out of credit) or 429 (too many active browsers).
+
+Every browser runs Browser Use's hardened Chromium with stealth and anti-fingerprinting
+on by default, plus a US residential proxy and automatic CAPTCHA solving — there is no
+stealth flag to set.
+
+## Profiles
+
+The profile value here is a provider-assigned **profile id** (a UUID), not a name you
+mint: in SKILL.md's first-time bootstrap, REPLACE the minted `$PROFILE` with the id from a
+profile create, then continue with the keychain registration unchanged:
+
+```bash
+PROFILE=$(curl -fsS -X POST https://api.browser-use.com/api/v4/profiles \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" -H 'content-type: application/json' \
+ -d '{"name":"qm"}' \
+ | python3 -c "import sys,json;print(json.load(sys.stdin)['id'])")
+[ -n "$PROFILE" ] || { echo "profile create returned no id" >&2; exit 1; }
+export "$PROFILE_ENV"="$PROFILE"
+```
+
+A profile stores cookies and local storage. Rules that keep sign-ins alive:
+
+- **State is written when the browser stops**, either by the stop call in Clean up or by
+ hitting its `timeout`. Nothing is saved while it runs, and closing CDP (or the runner
+ exiting) does not stop it. Stop explicitly rather than waiting out the timeout.
+- **One browser per profile at a time.** Stop the running browser before starting another
+ on the same profile; parallel sessions on one login invite forced logouts.
+- **Give the write-back a beat.** Wait ~10 seconds after a stop before launching the next
+ browser on that profile.
+- **Use the default browser context.** A fresh incognito context (`new_context()`) does
+ not inherit the profile's cookies.
+
+`GET /profiles/$BROWSER_USE_PROFILE` returns `cookieDomains` — the quickest check of which
+sites the profile holds state for.
+
+## Create the browser
+
+In a DM, with the person's profile. First make sure no browser is still running on the
+person's profile — state is written only when a browser stops, so one left running holds
+it. The v4 list doesn't say which profile a session is on, so every browser this doc
+creates is tagged with its profile id in `metadata`, and the check stops only tagged
+holders of this profile. An active browser with no tag is not yours to stop sight unseen:
+on a shared key it is someone else's task (leave it and say so), and on the person's own
+key it can only be one of their older browsers — stop it by hand before creating.
+Stopping a holder is also what saves it, so nothing is lost. The check is not a lock —
+two creates in the same moment can both pass it — so keep one browse run at a time on a
+person's profile:
+
+```bash
+ACTIVE=$(curl -fsS "https://api.browser-use.com/api/v4/browsers?filterBy=active" \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ | python3 -c "import sys,json,os;p=os.environ['BROWSER_USE_PROFILE'];print(' '.join(b['id'] for b in json.load(sys.stdin)['items'] if b.get('status')=='active' and (b.get('metadata') or {}).get('profileId')==p))")
+if [ -n "$ACTIVE" ]; then
+ for B in $ACTIVE; do
+ curl -fsS -X PATCH "https://api.browser-use.com/api/v4/browsers/$B" \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" -H 'content-type: application/json' \
+ -d '{"action":"stop"}' > /dev/null
+ done
+ sleep 10
+fi
+```
+
+Then create (the `metadata` tag is what the check above matches):
+
+```bash
+CREATE=$(curl -fsS -X POST https://api.browser-use.com/api/v4/browsers \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" -H 'content-type: application/json' \
+ -d "{\"profileId\":\"$BROWSER_USE_PROFILE\",\"timeout\":30,\"metadata\":{\"profileId\":\"$BROWSER_USE_PROFILE\"}}")
+BU_SID=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(sys.stdin)['id'])")
+CDP_BASE=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(sys.stdin)['cdpUrl'].rstrip('/'))")
+CDP_URL=$(curl -fsS "$CDP_BASE/json/version" \
+ | python3 -c "import sys,json;print(json.load(sys.stdin)['webSocketDebuggerUrl'])")
+LIVE_VIEW=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(sys.stdin)['liveUrl'])")
+```
+
+`cdpUrl` is an `https://…cdp.browser-use.com` base; the `/json/version` hop turns it into
+the websocket the runner drives. Both it and `LIVE_VIEW` are bearer material — anyone
+holding either controls the browser.
+
+In a channel or group, OMIT `profileId` (per the DM-only rule):
+
+```bash
+CREATE=$(curl -fsS -X POST https://api.browser-use.com/api/v4/browsers \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" -H 'content-type: application/json' \
+ -d '{"timeout":30}')
+```
+
+then extract `BU_SID` / `CDP_URL` / `LIVE_VIEW` exactly as above.
+
+`timeout` is minutes (1–240). `proxyCountryCode` defaults to `"us"`; pass another ISO
+code to change it, or `null` to drop the proxy. Browsers bill per minute, refunded
+pro rata on stop.
+
+## Giving the browser a file
+
+The browser's filesystem is not reachable from here, and `file://` pages are blocked, so
+the runner's `available_file_paths` route does not apply. Hand the file to the page
+directly instead: open the page with the file input, then inject the bytes over CDP.
+Point `SELECTOR` at the target input:
+
+```bash
+cat > /tmp/bu-attach.mjs <<'JS'
+import fs from "fs";
+const [, , wsUrl, filePath, selector] = process.argv;
+const ws = new WebSocket(wsUrl);
+let id = 0; const pending = new Map();
+const send = (method, params = {}, sessionId) => new Promise((resolve, reject) => { const i = ++id; pending.set(i, m => (m.error ? reject(new Error(m.error.message)) : resolve(m))); ws.send(JSON.stringify({ id: i, ...(sessionId ? { sessionId } : {}), method, params })); });
+ws.onmessage = e => { const m = JSON.parse(e.data); if (m.id && pending.has(m.id)) { pending.get(m.id)(m); pending.delete(m.id); } };
+ws.onclose = () => { for (const r of pending.values()) r({ error: { message: "cdp socket closed" } }); pending.clear(); };
+await new Promise(r => ws.onopen = r);
+const { targetInfos } = (await send("Target.getTargets")).result;
+const page = targetInfos.find(t => t.type === "page");
+if (!page) throw new Error("no page target on the browser");
+const { sessionId } = (await send("Target.attachToTarget", { targetId: page.targetId, flatten: true })).result;
+const b64 = fs.readFileSync(filePath).toString("base64");
+const name = filePath.split("/").pop();
+const expression = `(()=>{const s=atob(${JSON.stringify(b64)});const u=new Uint8Array(s.length);for(let i=0;i<s.length;i++)u[i]=s.charCodeAt(i);
+const dt=new DataTransfer();dt.items.add(new File([u],${JSON.stringify(name)}));const el=document.querySelector(${JSON.stringify(selector)});
+if(!el)throw new Error("no element matches the selector");el.files=dt.files;el.dispatchEvent(new Event("input",{bubbles:true}));el.dispatchEvent(new Event("change",{bubbles:true}));return el.files[0].size})()`;
+const { result } = await send("Runtime.evaluate", { expression, returnByValue: true }, sessionId);
+if (result.exceptionDetails) throw new Error(`page rejected the injection: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}`);
+console.log(JSON.stringify(result.result));
+ws.close();
+JS
+node /tmp/bu-attach.mjs "$CDP_URL" /tmp/receipt.jpg "$SELECTOR"
+```
+
+The script exits non-zero when a protocol call fails or the page throws (a selector that
+matches nothing, a blocked page) — treat that as the attach having failed: read the error
+and fix it, don't re-run the task assuming the file is attached. Then run the task telling
+the agent the file is already attached. Keep files small (this inlines the bytes); a site
+that reads the file only through a native picker dialog won't see it.
+
+## Routing a sign-in wall
+
+The person signs in THEMSELVES through the live view; the profile keeps them signed in
+afterwards. Reuse the task browser — it already holds the profile — and steer it to the wall with SKILL.md's shared `browse-nav.py`:
+
+```bash
+CDP_URL="$CDP_URL" /opt/browser-engine/venv/bin/python /tmp/browse-nav.py
+printf '%s\n' "$LIVE_VIEW"
+```
+
+Hand them `$LIVE_VIEW`: they sign in, finish any 2FA, and say done. Confirm the page now
+shows them signed in, then STOP the browser (that is what writes the profile), wait
+~10 seconds, create a fresh browser on the same profile, and re-run the task. The profile
+replays cookies; it cannot answer a challenge, so a site that re-verifies on every visit
+needs the person again next time.
+
+A mid-session verification check needs no stop — SKILL.md's live-view rule covers it.
+
+## Clean up
+
+Always stop the browser. The runner leaves it running, so it otherwise bills until its
+timeout, and the stop is what saves the profile:
+
+```bash
+curl -fsS -X PATCH "https://api.browser-use.com/api/v4/browsers/$BU_SID" \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" -H 'content-type: application/json' \
+ -d '{"action":"stop"}'
+```
+
+## API reference
+
+Read these instead of guessing when a call surprises you (the full bundle is
+https://docs.browser-use.com/.well-known/llms-full.txt):
+
+- Browsers (create, stop, timeout, proxy): https://docs.browser-use.com/cloud/api-v4/browsers/create-browser-session.md
+- Profiles: https://docs.browser-use.com/cloud/guides/authentication.md
+- CDP control: https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium.md
+- Live view: https://docs.browser-use.com/cloud/browser/live-preview.md
+- Stealth, proxies, CAPTCHAs: https://docs.browser-use.com/cloud/browser/stealth.md
diff --git a/skills-seed/browse/providers/browserbase.md b/skills-seed/browse/providers/browserbase.md
index 51335c011..63686af8e 100644
--- a/skills-seed/browse/providers/browserbase.md
+++ b/skills-seed/browse/providers/browserbase.md
@@ -113,25 +113,13 @@ SIGNIN_SID=$(printf '%s' "$SIGNIN" | python3 -c "import sys,json;print(json.load
SIGNIN_CDP=$(printf '%s' "$SIGNIN" | python3 -c "import sys,json;print(json.load(sys.stdin).get('connectUrl',''))")
```
-It opens on a blank page, so steer it to the wall, then fetch the live-view link
+It opens on a blank page, so steer it to the wall with SKILL.md's shared
+`browse-nav.py`, then fetch the live-view link
(`keepAlive` is what lets the session survive the nav script disconnecting — without it
the person would open a dead live view):
```bash
-cat > /tmp/bb-nav.py <<'PY'
-import os
-from playwright.sync_api import sync_playwright
-with sync_playwright() as p:
- b = p.chromium.connect_over_cdp(os.environ["SIGNIN_CDP"])
-
-
-
- ctx = b.contexts[0]
- page = ctx.pages[0] if ctx.pages else ctx.new_page()
- page.goto(open("/tmp/wall-url.txt").read().strip(), timeout=60000)
- b.close()
-PY
-SIGNIN_CDP="$SIGNIN_CDP" /opt/browser-engine/venv/bin/python /tmp/bb-nav.py
+CDP_URL="$SIGNIN_CDP" /opt/browser-engine/venv/bin/python /tmp/browse-nav.py
curl -fsS "https://api.browserbase.com/v1/sessions/$SIGNIN_SID/debug" \
-H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
| python3 -c "import sys,json;print(json.load(sys.stdin).get('debuggerFullscreenUrl',''))"
diff --git a/skills-seed/browse/providers/kernel.md b/skills-seed/browse/providers/kernel.md
index b99f4c630..08a3ba1f1 100644
--- a/skills-seed/browse/providers/kernel.md
+++ b/skills-seed/browse/providers/kernel.md
@@ -7,8 +7,17 @@ Provider names for the shared flow in SKILL.md: API key `KERNEL_API_KEY`, keycha
export PROFILE_ENV=KERNEL_PROFILE PROFILE_SERVICE=kernel-profile
```
+In a DM, name three handles in `credentials`: the Kernel key (if it isn't org env), the
+person's `KERNEL_PROFILE`, and their `KERNEL_PROXY_ID` (see "The person's static IP").
+
## Profiles
+The person's profile is a Kernel browser profile whose name lives in their keychain
+(`KERNEL_PROFILE`). It holds their sign-ins: a browser launched with it starts signed in,
+and a browser launched with `save_changes: true` writes its cookies back when it is
+DELETED or times out (closing CDP does not save). No Managed Auth: the person signs in
+once on the live view and the profile keeps it.
+
Kernel profiles must be pre-created at the API — a browser create naming a profile that
doesn't exist 400s (that's the usual cause of a 400 here, not a Kernel outage). During
first-time setup, and whenever the create below 400s, create the profile under the EXISTING
@@ -20,21 +29,63 @@ curl -fsS -X POST https://api.onkernel.com/profiles \
-d "{\"name\":\"$KERNEL_PROFILE\"}" > /dev/null
```
+## The person's static IP
+
+Each person also gets their own Kernel ISP proxy: a static exit IP on a residential ISP,
+the same on every session. Sites that remember devices (LinkedIn especially) see one
+person on one connection instead of a new address every run, which is what keeps a
+saved sign-in from tripping verification. Its id lives in their keychain as
+`KERNEL_PROXY_ID` (service `kernel-proxy`); treat it like the profile name (it decides
+whose address the browser wears), so it comes only from the keychain, in a DM.
+
+If the manifest has no `KERNEL_PROXY_ID` handle, run the same existence check SKILL.md
+gives for the profile (`envKey == "KERNEL_PROXY_ID"`). Only when none exists, create one
+with the person's OK (it is a paid, per-person resource) and register it:
+
+```bash
+PX=$(curl -fsS -X POST https://api.onkernel.com/proxies \
+ -H "Authorization: Bearer $KERNEL_API_KEY" -H 'content-type: application/json' \
+ -d '{"type":"isp","name":"qm-<person>-isp","config":{"country":"US"}}' \
+ | python3 -c "import sys,json;print(json.load(sys.stdin)['id'])")
+[ -n "$PX" ] || { echo "proxy create returned no id; nothing registered" >&2; exit 1; }
+curl -fsS -X POST "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capability: $AGENT_API_TOKEN" \
+ -H 'content-type: application/json' \
+ -d "{\"service\":\"kernel-proxy\",\"envKey\":\"KERNEL_PROXY_ID\",\"secret\":\"$PX\"}" > /dev/null
+```
+
+ISP proxies exist in US, GB, FR, DE and SG; pick the person's country. Use the person's
+own `KERNEL_API_KEY` for this when they have one (a shared brokered Kernel credential
+may only allow `/browsers` and `/profiles`). The first session from the new IP may ask the
+person to verify once on sites they were already signed in to elsewhere; after that it is
+stable. If a create fails on the proxy (`proxy_id` not found), check it with
+`POST /proxies/$KERNEL_PROXY_ID/check` and tell the person rather than silently launching
+without it.
+
## Create the browser
-In a DM, with the person's profile:
+In a DM, with the person's profile and proxy. Only ONE browser may write to a profile at a
+time: Kernel allows concurrent browsers on a profile, and each save replaces the whole
+profile, so a second writer silently clobbers the first. Check for a running browser on
+the profile first, and launch read-only when one exists:
```bash
+SAVE=$(curl -fsS https://api.onkernel.com/browsers -H "Authorization: Bearer $KERNEL_API_KEY" \
+ | python3 -c "import sys,json,os;p=os.environ['KERNEL_PROFILE'];print('false' if any((b.get('profile') or {}).get('name')==p for b in json.load(sys.stdin)) else 'true')")
CREATE=$(curl -fsS -X POST https://api.onkernel.com/browsers \
-H "Authorization: Bearer $KERNEL_API_KEY" -H 'content-type: application/json' \
- -d "{\"stealth\":true,\"headless\":false,\"timeout_seconds\":1800,\"profile\":{\"name\":\"$KERNEL_PROFILE\"}}")
+ -d "{\"stealth\":true,\"headless\":false,\"timeout_seconds\":1800,\"proxy_id\":\"$KERNEL_PROXY_ID\",\"profile\":{\"name\":\"$KERNEL_PROFILE\",\"save_changes\":$SAVE}}")
CDP_URL=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(sys.stdin).get('cdp_ws_url',''))")
KERNEL_SID=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(sys.stdin).get('session_id',''))")
LIVE_VIEW=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(sys.stdin).get('browser_live_view_url',''))")
```
-In a channel or group, OMIT the profile field entirely (per the DM-only rule) — never send
-an empty or personal profile name there:
+`CDP_URL` is the websocket the runner drives directly. If `SAVE` came back `false`, say so
+when you report: anything this run signs in to won't be kept. The check is not a lock —
+two creates in the same moment can both see an empty list — so keep one browse run at a
+time on a person's profile.
+
+In a channel or group, OMIT the profile AND `proxy_id` entirely (per the DM-only rule) —
+never send a personal profile name or proxy there:
```bash
CREATE=$(curl -fsS -X POST https://api.onkernel.com/browsers \
@@ -44,12 +95,6 @@ CREATE=$(curl -fsS -X POST https://api.onkernel.com/browsers \
then extract `CDP_URL` / `KERNEL_SID` / `LIVE_VIEW` from `$CREATE` exactly as above.
-The profile is the person's own browsing state — their sign-ins persist in it across runs,
-so every browser you launch this way starts already signed in to whatever they've connected.
-It loads read-only: state gets INTO it via the Managed Auth hosted flow (below), never from
-your browsing. (Kernel also supports `profile.save_changes: true` to write a session's
-cookies back on browser DELETE — don't use it; concurrent runs would race their writes.)
-
## Giving the browser a file
Files land in `/home/kernel`:
@@ -64,91 +109,28 @@ Then run the task with `BROWSE_FILES="/home/kernel/receipt.jpg"` per SKILL.md.
## Routing a sign-in wall
-The FULL Managed Auth flow is available against the person's profile — prefer it (the
-session persists for all their future runs; a live-view login lives only as long as this
-browser).
-
-**Pre-store the person's login at Kernel whenever they'll let you** — this is the reliable
-path, per Kernel's own guidance. Without a linked credential the hosted page discovers the
-login form live and on some sites stalls at "Discovering login requirements…" until the
-link times out (seen on doordash.com); with one, Kernel skips discovery, auto-fills, and
-can re-auth automatically when the session lapses (only an OTP still needs the person).
-
-1. **Get the login into their keychain** (skip to step 3's plain hosted link only if they
- decline). Check `GET /v1/keychain/credentials` first — a credential whose service/name
- matches the walled domain may already exist (use it via a grant; NEVER bind a login
- registered for a different site). Otherwise mint a one-time secret-drop so the password
- never transits chat, and ask which way they sign in — a Google-SSO site needs the
- Google login, not a site password:
- ```bash
- curl -fsS -X POST "$AGENT_API_URL/v1/keychain/drops" -H "x-agent-capability: $AGENT_API_TOKEN" \
- -H 'content-type: application/json' \
- -d '{"service":"<domain>","fields":[{"key":"EMAIL","secret":false},{"key":"PASSWORD"}],"purpose":"sign in to <domain> in the managed browser"}'
- ```
- Hand over the returned `url` with the consent stated plainly: _filling it stores this
- login with Kernel (our managed-browser provider) so it can sign in and re-sign-in for
- you_ — that storage is the point, and it needs their explicit OK. Redemption fires a
- wake back into this conversation, and since sign-ins are DM-only the person's own
- credential is usable on that next turn by naming its handle in `credentials` (which sets
- `EMAIL`/`PASSWORD` for that command — no grant dance needed).
-2. **Store the credential at Kernel, then create the connection WITH it linked.** Linking
- only works at connection create — if an unlinked connection for the domain already
- exists (the create 409s with `existing_id`), DELETE it first and re-create. Names must
- be fresh per store (Kernel 409s on reuse — never a silent overwrite). Build bodies with
- Python from env; the secret never rides shell source, and the temp file is removed:
- ```bash
- export CRED_NAME="<domain>-$(python3 -c 'import secrets;print(secrets.token_hex(4))')"
- python3 -c 'import json,os,sys
- domain, name, sso = sys.argv[1], sys.argv[2], os.environ.get("SSO_PROVIDER","")
- body={"name":name,"domain":("accounts.google.com" if sso=="google" else domain),
- **({"sso_provider":sso} if sso else {}),
- "values":{"email":os.environ["EMAIL"],"password":os.environ["PASSWORD"]}}
- print(json.dumps(body))' "<the walled domain>" "$CRED_NAME" > /tmp/cred-body.json
- curl -fsS -X POST https://api.onkernel.com/credentials \
- -H "Authorization: Bearer $KERNEL_API_KEY" -H 'content-type: application/json' \
- --data-binary @/tmp/cred-body.json > /dev/null && rm -f /tmp/cred-body.json
- ```
- (`SSO_PROVIDER=google` when they sign in with Google — the credential's domain is then
- `accounts.google.com`, exactly as Kernel's docs prescribe.) Then the connection — read
- the wall URL from `/tmp/wall-url.txt` (extracted in SKILL.md; it never transits shell
- source) and let Python build the JSON. Pass the wall URL as `login_url` too (skips
- discovery even without a credential):
- ```bash
- python3 -c 'import json,os,sys,urllib.parse
- url=open("/tmp/wall-url.txt").read().strip()
- cred=os.environ.get("CRED_NAME","")
- print(json.dumps({"domain": urllib.parse.urlsplit(url).hostname or "", "profile_name": sys.argv[1],
- "login_url": url, **({"credential":{"name":cred}} if cred else {})}))' \
- "$KERNEL_PROFILE" > /tmp/conn-body.json
- CONN=$(curl -sS -X POST https://api.onkernel.com/auth/connections \
- -H "Authorization: Bearer $KERNEL_API_KEY" -H 'content-type: application/json' --data-binary @/tmp/conn-body.json)
+The person signs in once on the live browser; the profile keeps it.
+1. Navigate the live browser to the wall URL (read from `/tmp/wall-url.txt`, never shell
+ source) so the person lands on the login page, then hand them `$LIVE_VIEW` in the DM —
+ bearer material, never open it yourself. SKILL.md's shared `browse-nav.py` (written in
+ its wall step) does the steering:
- CONN_ID=$(printf '%s' "$CONN" | python3 -c "import sys,json;j=json.load(sys.stdin);print(j.get('id') or j.get('existing_id',''))")
- ```
-3. **Start the login flow** (`record_session: true` so a stuck flow is reviewable) and hand
- the person the hosted URL — single-use, expires in ~30 min, never open it yourself, and
- mint a fresh one if they lose it:
```bash
- curl -sS -X POST "https://api.onkernel.com/auth/connections/$CONN_ID/login" \
- -H "Authorization: Bearer $KERNEL_API_KEY" -H 'content-type: application/json' \
- -d '{"record_session":true}' \
- | python3 -c "import sys,json;print(json.load(sys.stdin).get('hosted_url',''))"
+ CDP_URL="$CDP_URL" /opt/browser-engine/venv/bin/python /tmp/browse-nav.py
```
- With a linked credential the hosted page auto-fills and usually only surfaces the OTP
- step; without one the person types their login there. Expectation-setting: an SMS/email
- OTP step always needs the person — including again on re-auth after the session lapses —
- so 2FA-heavy sites are better, not hands-free. Avoid Kernel's programmatic login flow
- (poll `/auth/connections/:id` and submit fields): it can loop forever on sites that
- re-ask the same field (seen live on DoorDash's email step) — if you try it anyway, give
- up after ~3 resubmits of the same fieldset and fall back to the hosted link.
-4. When they say they're done, confirm `status` is `AUTHENTICATED` via
- `GET /auth/connections/$CONN_ID`, then DELETE the old browser, create a fresh one
- (it launches with the now-signed-in profile), and re-run the task. If the flow instead
- gets stuck at "Discovering login requirements…", delete the connection, get a credential
- stored (step 1 — this is exactly the failure it prevents), and re-create linked.
-
-The profile is theirs alone, so signing in real accounts is fine — that's the point.
+
+2. They sign in, finish any 2FA, and say done. If the browser was launched with
+ `SAVE=false` (another browser holds the profile), stop that one first and relaunch, or
+ the sign-in is lost.
+3. DELETE the browser (that is what writes the profile), wait ~10s, create a fresh one
+ (it launches signed in) and re-run the task.
+
+Expectation-setting: the profile keeps session cookies; it can't re-answer challenges. A
+site that re-verifies on every visit (SMS/email OTP) will need the person again, and when
+a site eventually expires the session, the next run hits the wall and you repeat this.
+Don't use Kernel Managed Auth or stored Kernel credentials for this — the person's
+password never leaves them.
## Clean up
@@ -160,9 +142,6 @@ curl -fsS -X DELETE "https://api.onkernel.com/browsers/$KERNEL_SID" -H "Authoriz
Read these instead of guessing when a call surprises you:
-- Managed Auth: https://www.kernel.sh/docs/api-reference/managed-auth/create-auth-connection
- and https://www.kernel.sh/docs/api-reference/managed-auth/start-login-flow
-- Credentials (pre-store for auto-fill): https://www.kernel.sh/docs/auth/credentials
-- Programmatic login flows (SSO buttons, MFA options, flow states):
- https://www.kernel.sh/docs/auth/programmatic
+- Profiles (save_changes, concurrency): https://www.kernel.sh/docs/browsers/profiles
+- ISP proxies (static exit IP): https://www.kernel.sh/docs/proxies/isp
- Browsers (create/delete, profiles, live view, fs upload): https://www.kernel.sh/docs/api-reference/browsers