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.mdindex 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 connecOpenAI account, including refreshed subscription access; Claude access supportsAPI keys. Claude subscription access is unavailable for the inner browser agentand 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-streamingdiff --git a/skills-seed/browse/SKILL.md b/skills-seed/browse/SKILL.mdindex 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 skillbecoming 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`, theorg 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) meansnothing 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 providerflow 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-audiencebearer material — hand them to the person in a DM, never open them yourself; and amid-session verification check (already signed in, then challenged) is cleared on the LIVEbrowser — 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 upAlways 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.mdnew file mode 100644index 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.mddiff --git a/skills-seed/browse/providers/browserbase.md b/skills-seed/browse/providers/browserbase.mdindex 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.loadSIGNIN_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 itthe 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.pycurl -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.mdindex 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`, keychaexport 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 thatdoesn't exist 400s (that's the usual cause of a 400 here, not a Kernel outage). Duringfirst-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:```bashCREATE=$(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 fileFiles 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 "AuthorizRead 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