Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

browse/kernel: use the shared Kernel credential through the broker (#2384)

Joshua France5e5f15749d81
diff --git a/skills-seed/browse/SKILL.md b/skills-seed/browse/SKILL.md
index a720c553f..0f19800e8 100644
--- a/skills-seed/browse/SKILL.md
+++ b/skills-seed/browse/SKILL.md
@@ -21,13 +21,16 @@ Which provider you use is decided by which API key is available in your env (or
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:
+person's own keychain key overrides the org one. A provider can also be offered as a shared
+credential you call through QM's broker without ever holding the key; the provider doc
+says so when it supports that (Kernel does, via `service_kernel`). Keys you may see today:
Use the absolute directory reported by the skill read for all `providers/` paths below.
Keep the same explicit `sandbox_id` for the skill read and every `execute` command
in this flow, including the runner.
-- `KERNEL_API_KEY` → **Kernel** (onkernel.com). Read `providers/kernel.md`.
+- `KERNEL_API_KEY`, or a `service_kernel` shared credential in your inventory →
+ **Kernel** (onkernel.com). Read `providers/kernel.md`.
- `ANCHOR_API_KEY` → **Anchor** (anchorbrowser.io). Read `providers/anchor.md`.
- `BROWSERBASE_API_KEY` → **Browserbase** (browserbase.com). Read
`providers/browserbase.md`.
@@ -45,15 +48,12 @@ in this flow, including the runner.
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,
+runner below needs. This file owns everything else: when to browse at all,
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.
+**Always browse with the person's profile from their keychain.** If they don't have one
+yet, create one and store it in their keychain (first-time setup below).
## Prerequisites (each run)
@@ -99,8 +99,8 @@ of them (asks and drops are refused only on trigger-fired turns).
```bash
curl -fsS "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capability: $AGENT_API_TOKEN"
```
-2. **Registered to the person themselves** → in their DM, its handle is already usable in
- `credentials`. Anywhere else, send an ask (step 3); they approve it on the card.
+2. **Registered to the person themselves** → if its handle is in your manifest, use it in
+ `credentials`. Otherwise 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
@@ -122,7 +122,7 @@ curl -fsS "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capability: $AGEN
```
- **Credential exists** → use that handle in `credentials`. Never bootstrap in this case.
-- **No credential at all** → first-time setup below, with the person's OK.
+- **No credential at all** → first-time setup below.
**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
@@ -143,8 +143,8 @@ curl -fsS -X POST "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capabilit
## 1. Create the browser
-Follow your provider doc's "Create the browser" section. In a DM, launch it with the
-person's profile; in a channel or group, launch profile-less (per the DM-only rule). The
+Follow your provider doc's "Create the browser" section. Launch it with the
+person's profile. The
step leaves you with `CDP_URL` (the websocket the runner drives) and `LIVE_VIEW` (the
human-viewable session URL). Treat `CDP_URL` as a secret — some providers embed the API key
in it; it rides only as a runner argument, never into chat or logs.
@@ -267,7 +267,7 @@ The last stdout line is the typed outcome:
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
+ bearer material — hand them only to the person, 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.
diff --git a/skills-seed/browse/providers/anchor.md b/skills-seed/browse/providers/anchor.md
index b52cac85f..617e2ec81 100644
--- a/skills-seed/browse/providers/anchor.md
+++ b/skills-seed/browse/providers/anchor.md
@@ -31,7 +31,7 @@ the person asks to reset their state).
## Create the browser
-In a DM, with the person's profile:
+With the person's profile:
```bash
CREATE=$(curl -fsS -X POST https://api.anchorbrowser.io/v1/sessions \
@@ -42,16 +42,6 @@ ANCHOR_SID=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load
LIVE_VIEW=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(sys.stdin)['data'].get('live_view_url',''))")
```
-In a channel or group, OMIT the profile entirely (per the DM-only rule):
-
-```bash
-CREATE=$(curl -fsS -X POST https://api.anchorbrowser.io/v1/sessions \
- -H "anchor-api-key: $ANCHOR_API_KEY" -H 'content-type: application/json' \
- -d '{"session":{"timeout":{"max_duration":30,"idle_timeout":10}}}')
-```
-
-then extract `CDP_URL` / `ANCHOR_SID` / `LIVE_VIEW` from `$CREATE` exactly as above.
-
Timeouts are minutes (`max_duration` caps the session, `idle_timeout` reaps an unused one).
For a site behind serious bot protection, add a proxy and Anchor's hardened build — both
are billed extras, so reach for them on a block, not by default:
@@ -115,7 +105,7 @@ Hand over the returned `url` with the consent stated plainly: _filling it stores
with Anchor (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; name the new credential's handle in `credentials` to get
-`EMAIL`/`PASSWORD` for that command (sign-ins are DM-only, so no grant dance). Then create the identity with Python building the body from env
+`EMAIL`/`PASSWORD` for that command. Then create the identity with Python building the body from env
(`POST /v1/identities` with `{"source":"https://<domain>","name":...,"credentials":
[{"type":"username_password","username":...,"password":...}]}`), and register the returned
identity id in their keychain (service `anchor-identity`, envKey
diff --git a/skills-seed/browse/providers/browser-use.md b/skills-seed/browse/providers/browser-use.md
index 71023fb73..8d52baad0 100644
--- a/skills-seed/browse/providers/browser-use.md
+++ b/skills-seed/browse/providers/browser-use.md
@@ -48,7 +48,7 @@ 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
+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
@@ -90,16 +90,6 @@ LIVE_VIEW=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(
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.
diff --git a/skills-seed/browse/providers/browserbase.md b/skills-seed/browse/providers/browserbase.md
index 63686af8e..c4b4807b8 100644
--- a/skills-seed/browse/providers/browserbase.md
+++ b/skills-seed/browse/providers/browserbase.md
@@ -44,7 +44,7 @@ again through the same live-view flow below.
`keepAlive` matters everywhere here: without it the session dies as soon as a CDP client
disconnects, so a runner retry or the sign-in handoff below would find a dead browser.
-(It needs the Hobby plan or above.) In a DM, with the person's context:
+(It needs the Hobby plan or above.) With the person's context:
```bash
CREATE=$(curl -fsS -X POST https://api.browserbase.com/v1/sessions \
@@ -62,16 +62,6 @@ goes stale once the task opens more tabs. Whenever you hand a live-view link ove
re-fetch `/v1/sessions/$BB_SID/debug` at hand-off time and pick the right entry from
`pages[]` (each has its own `debuggerFullscreenUrl`, `url`, and `title`).
-In a channel or group, OMIT `browserSettings.context` entirely (per the DM-only rule):
-
-```bash
-CREATE=$(curl -fsS -X POST https://api.browserbase.com/v1/sessions \
- -H "X-BB-API-Key: $BROWSERBASE_API_KEY" -H 'content-type: application/json' \
- -d '{"keepAlive":true,"timeout":1800}')
-```
-
-then extract `CDP_URL` / `BB_SID` / `LIVE_VIEW` exactly as above.
-
Timeout is seconds (60–21600); captcha solving is on by default. For a site behind
serious bot protection, add top-level `"proxies":true` and
`"browserSettings":{"advancedStealth":true}` (a Scale-plan feature) — billed extras,
diff --git a/skills-seed/browse/providers/kernel.md b/skills-seed/browse/providers/kernel.md
index e51bcc00a..8b8ffc1a5 100644
--- a/skills-seed/browse/providers/kernel.md
+++ b/skills-seed/browse/providers/kernel.md
@@ -7,25 +7,82 @@ 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
+Name three handles in `credentials`: the Kernel key (see "Which key" below), the
person's `KERNEL_PROFILE`, and their `KERNEL_PROXY_ID` (see "The person's static IP").
+## Which key
+
+Use the first of these that exists:
+
+1. **The person's own key**: a `KERNEL_API_KEY` handle of theirs in your keychain
+ manifest. Name it in `credentials`.
+2. **An org key delivered as env**: `KERNEL_API_KEY` already set in your shell.
+3. **The org's shared Kernel credential**: a `service_kernel` row in the Credentials
+ inventory (proxy, host `api.onkernel.com`). Name `service_kernel` in `credentials`.
+ You never see this key. QM adds it to each request you send through its credential
+ broker (see the use-shared-credential skill), so `KERNEL_API_KEY` stays unset.
+
+Make every Kernel API call in this doc through `kapi METHOD PATH [JSON-BODY]`, which
+picks the right route, prints the response body, and on any error exits non-zero with
+the status and body on stderr. Define it once per shell:
+
+```bash
+kapi() {
+ if [ -n "${KERNEL_API_KEY:-}" ]; then
+ if [ -n "${3:-}" ]; then
+ curl -fsS -X "$1" "https://api.onkernel.com$2" -H "Authorization: Bearer $KERNEL_API_KEY" \
+ -H 'content-type: application/json' -d "$3"
+ else
+ curl -fsS -X "$1" "https://api.onkernel.com$2" -H "Authorization: Bearer $KERNEL_API_KEY"
+ fi
+ else
+ python3 - "$1" "$2" "${3:-}" <<'PY'
+import json, os, sys, urllib.error, urllib.request
+method, path, body = sys.argv[1:4]
+req = {"credential": "kernel", "method": method, "url": "https://api.onkernel.com" + path}
+if body:
+ req["headers"] = {"content-type": "application/json"}
+ req["body"] = body
+r = urllib.request.Request(os.environ["AGENT_API_URL"] + "/v1/credentials/broker",
+ data=json.dumps(req).encode(), method="POST",
+ headers={"x-agent-capability": os.environ["AGENT_CREDENTIAL_TOKEN"], "content-type": "application/json"})
+try:
+ env = json.load(urllib.request.urlopen(r))
+except urllib.error.HTTPError as e:
+ sys.stderr.write(f"broker {e.code}: {e.read().decode()[:500]}\n"); sys.exit(1)
+if not 200 <= env.get("status", 0) < 300:
+ sys.stderr.write(f"kernel {env.get('status')}: {(env.get('body') or '')[:500]}\n"); sys.exit(1)
+sys.stdout.write(env.get("body") or "")
+PY
+ fi
+}
+```
+
+The shared credential only creates and deletes (see "Org setup"), so with it you can't
+list or read anything back, and can't upload files (the broker carries JSON, not
+multipart). The flow below needs neither.
+
## Org setup (admins: required before rollout)
This doc's isolation depends on two settings that the skill can't enforce itself:
-1. **Shared credential: create and delete only.** Configure the org's shared Kernel
- credential (the broker entry for `api.onkernel.com`) with methods `POST` and `DELETE`
- only, on paths `/browsers` and `/profiles`. Do NOT allow `GET`: the paths match by
- prefix, so any `GET` lets callers list every person's profiles and running browsers,
+1. **Shared credential: its own project, create and delete only.** Give QM's shared key
+ a dedicated Kernel project and a key restricted to it (`browsers`, `profiles` and
+ `proxies`, each with `use`, `create`, `write` and `delete` on `projects/<id>/*`, and no
+ `read`). Kernel requires project-wide `browsers:use` to create a browser at all, and
+ that also lets the key list and attach to every running browser in its project, so
+ never put the shared key in a project that people's own keys or other tools use. Then
+ configure the broker entry for `api.onkernel.com` with methods `POST` and `DELETE` only,
+ on paths `/browsers`, `/profiles` and `/proxies`. Do NOT allow `GET`: the paths match
+ by prefix, so any `GET` lets callers list every person's profiles and running browsers,
and their names are all anyone needs to open someone else's signed-in browser.
Nothing in this flow needs `GET`; the live view and CDP URL come back from the create.
2. **Personal keys scoped to the person.** A person's own `KERNEL_API_KEY` must not be an
- account-wide key on the shared Kernel account; it would bypass rule 1. Give them their
- own Kernel project (or a key restricted to their project), so the only profiles it can
- see are theirs.
+ account-wide key; it would bypass rule 1. Give them their own Kernel project and a key
+ restricted to it, for the same reason as above: within one project, any key that can
+ create browsers can see every running browser.
-If you're an agent and the shared credential's listing shows `GET`, tell the person
+If you're an agent and the `service_kernel` row in your inventory allows `GET`, tell the person
(and an org admin) that profiles aren't isolated yet. Don't work around it.
## Profiles
@@ -49,9 +106,7 @@ first-time setup, and whenever the create below 400s, create the profile under t
name from the keychain — never a fresh random one, which would orphan the credential:
```bash
-curl -fsS -X POST https://api.onkernel.com/profiles \
- -H "Authorization: Bearer $KERNEL_API_KEY" -H 'content-type: application/json' \
- -d "{\"name\":\"$KERNEL_PROFILE\"}" > /dev/null
+kapi POST /profiles "{\"name\":\"$KERNEL_PROFILE\"}" > /dev/null
```
## The person's static IP
@@ -61,16 +116,14 @@ the same on every session. Sites that remember devices (LinkedIn especially) see
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.
+whose address the browser wears), so it comes only from the keychain.
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"}}' \
+PX=$(kapi POST /proxies '{"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" \
@@ -78,17 +131,18 @@ curl -fsS -X POST "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capabilit
-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
+ISP proxies exist in US, GB, FR, DE and SG; pick the person's country. If the shared
+credential refuses `/proxies` (path_not_allowed), the org hasn't enabled it; launch
+without a proxy and tell the person. 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.
+`kapi POST /proxies/$KERNEL_PROXY_ID/check` (own or env key only; the shared credential
+has no read access, so the check is refused) and tell the person rather than silently
+launching without it.
## Create the browser
-In a DM, with the person's profile and proxy. Only ONE browser may write to a profile at a
+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. Since browsers can't be listed,
record your own writer in the person's keychain (`KERNEL_ACTIVE`, service
@@ -99,9 +153,7 @@ no writer):
```bash
SAVE=true
case "${KERNEL_ACTIVE:-}" in *:*) [ $(( $(date +%s) - ${KERNEL_ACTIVE#*:} )) -lt 1800 ] && SAVE=false;; esac
-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,\"proxy_id\":\"$KERNEL_PROXY_ID\",\"profile\":{\"name\":\"$KERNEL_PROFILE\",\"save_changes\":$SAVE}}")
+CREATE=$(kapi POST /browsers "{\"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',''))")
@@ -120,20 +172,10 @@ when you report: anything this run signs in to won't be kept. The record is not
two runs starting in the same moment can both see none — 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 \
- -H "Authorization: Bearer $KERNEL_API_KEY" -H 'content-type: application/json' \
- -d '{"stealth":true,"headless":false,"timeout_seconds":1800}')
-```
-
-then extract `CDP_URL` / `KERNEL_SID` / `LIVE_VIEW` from `$CREATE` exactly as above.
-
## Giving the browser a file
-Files land in `/home/kernel`:
+Files land in `/home/kernel`. This needs a real key (own or env); the shared credential
+can't carry a file upload, so say so rather than improvising:
```bash
curl -fsS -X POST "https://api.onkernel.com/browsers/$KERNEL_SID/fs/upload" \
@@ -148,7 +190,7 @@ Then run the task with `BROWSE_FILES="/home/kernel/receipt.jpg"` per SKILL.md.
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 —
+ source) so the person lands on the login page, then hand them `$LIVE_VIEW` —
bearer material, never open it yourself. SKILL.md's shared `browse-nav.py` (written in
its wall step) does the steering:
@@ -171,7 +213,7 @@ password never leaves them.
## Clean up
```bash
-curl -fsS -X DELETE "https://api.onkernel.com/browsers/$KERNEL_SID" -H "Authorization: Bearer $KERNEL_API_KEY"
+kapi DELETE "/browsers/$KERNEL_SID"
# release the profile if this run held it
[ "$SAVE" = true ] && curl -fsS -X POST "$AGENT_API_URL/v1/keychain/credentials" \
-H "x-agent-capability: $AGENT_API_TOKEN" -H 'content-type: application/json' \