This page covers the agent host on a managed deploy when it is not a
Debian machine you can run
provision-connector.sh
on. That is usually a hosted agent runtime: a container or VM that a
dashboard or a third party runs, where the agent is root and the
operator has no shell. The #121/#201 pilot ran that way. It also
covers how the operator hands the agent its three values without
ever putting a secret in chat or on a command line.
Read Agent host first. It
explains path (B), the connector config and --check. Everything
there still applies; this page only replaces the script with manual
steps and says what changes when the agent is root.
| Value | Secret? | Where it goes | Made by |
|---|---|---|---|
| Tunnel credential | Yes | A file the connector reads (token_file), mode 0400 or 0600 |
kharon tunnel mint <agent> on the broker |
Agent token (kh_agent_<id>_…) |
Yes | The agent's MCP client, as the bearer for POST https://<host>/mcp |
kharon token mint <agent> |
broker_pin |
No, but it must arrive unaltered | connector.toml |
openssl x509 -outform DER | sha256sum on the inner [connector] certificate |
Plus the connector binary (kharon-agent-connector, built from this
repo) and, with an authenticating egress proxy, a proxy credential
file. The connector never holds the agent token, and the MCP client
never holds the tunnel credential (REQ-ARCH-001).
Do these in the runtime, as whoever can install software there (often the agent itself, or the runtime's setup script). None of them needs a secret except step 5.
- Chromium with CDP on loopback. Run Chromium (or Chrome) with
--remote-debugging-address=127.0.0.1 --remote-debugging-port=9222and its own--user-data-dir. Headless is fine. A runtime that cannot give Chromium a user namespace needs--no-sandbox; the pilot ran that way under an AppArmor user-namespace restriction. Keep it running with whatever supervisor the runtime has (systemd, s6, a process manager, the runtime's own restart policy). - The managed policy. Write the same JSON the script writes,
with password manager, leak detection, autofill, payment-method
query, sync and metrics off, to the policy directory of the
browser you run:
/etc/chromium/policies/managed/for Debian'schromium,/etc/opt/chrome/policies/managed/for Google Chrome,/etc/opt/chrome_for_testing/policies/managed/for Chrome for Testing (the browser Hermes packages). The file is inprovision-connector.sh(no-password-manager.json). Check it took effect: openchrome://policythrough CDP and look for the seven policies, each with source Platform and level Mandatory. The status column depends on the browser version. Chrome for Testing 145 showed all seven as OK (#339). Debian's Chromium 156 showed five as OK andAutofillAddressEnabledandAutofillCreditCardEnabledasDeprecated(#336);autofill.profile_enabledwas still managed and off there, and the credit-card pref was not checked. Without the file Chromium may offer to save a filled password (REQ-ARCH-004). ptrace_scope. Setkernel.yama.ptrace_scope = 1if the runtime lets you. In most containers it is the host's setting and you can't. Either way it doesn't stop root (see below).- The connector binary. Copy
kharon-agent-connectorto/usr/local/bin/(mode0755). It has no secret in it, so any file transfer the runtime offers is fine. Build it on a machine with this repo:cargo build --release -p kharon-agent-connector. - The tunnel credential file. Put it at
/etc/kharon-connector/token, mode0400, owned by the uid that runs the connector. See Handing over the secrets for how it gets there. The connector refuses a file readable by group or others. The connector reads the file only when it starts: after replacing the credential, restart the connector. connector.toml. Write/etc/kharon-connector/connector.tomlas in Connector config over WebSocket:transport = "ws",broker_url = "wss://<host>/connector",broker_pin,agent_id,token_fileandcdp = "127.0.0.1:9222". This file holds no secret; mode0644is fine.- Check, then run. With nothing else running as this agent, run
kharon-agent-connector --config /etc/kharon-connector/connector.toml --checkand expectcheck: ok. A successful check replaces any live session for this agent, so don't run it as a health probe. Then run the connector under the runtime's supervisor with the same--configand no other arguments. Expectagent connector attached: … transport=wsin kharond's log. - The MCP client. Point it at
https://<host>/mcpwith the agent token asAuthorization: Bearer kh_agent_<id>_…, stored in the client's or the runtime's secret setting, never in a prompt or a file the model reads. A worked config is in MCP client. Tool names and schemas aredocs/api/mcp-tools.json. Apply the agent harness policy.
Every isolation boundary on the agent host is a Unix permission, and
root is exempt from all of them. A root agent can read Chromium's
profile, read the tunnel credential file, and attach to Chromium to
read /proc/<pid>/mem, where filled values live briefly. So on a
root runtime the steps above give you path (B)'s transport, the
approval flow and the audit log, but not REQ-GOAL-002's isolation.
Running the connector and Chromium as separate non-root users inside
the runtime helps only if the agent itself is not root. Tell the
customer which one they are getting.
Stock Hermes discovery reads the connector process's own
$HERMES_HOME, or $HOME/.hermes when that variable is unset. It
does not search another user's home.
provision-connector.sh
runs the connector as User=connector, home
/var/lib/kharon-connector, with ProtectHome=yes, and writes an
explicit cdp = "127.0.0.1:…". That unit is the fixed-port Chromium
install. Used as-is for stock Hermes, the preset scans
/var/lib/kharon-connector/.hermes, which Hermes never writes, and
ProtectHome=yes hides Hermes's real home under /home even when
hermes_home names it. --check still prints check: ok, because
it never opens the file. kharon_context and kharon_fill then
return error with detail cdp_error. A connector that is not
running at all shows up as timeout, not as the connector's
no_browser dial result and not as REQ-OAU-007's MCP no_browser.
On start the connector logs the path it will scan,
cdp: discover hermes_home=…. A later dial that cannot read a live
file logs cdp: discover failed, at most once a minute.
The setup that was checked on a stock Hermes host is to run the
connector as Hermes's own user. The default home is then Hermes's
home, and ProtectHome can stay.
A separate connector uid is the layout
provision-connector.sh
uses, and it is not yet shown to work for this preset. Hermes
creates ~/.hermes, the ephemeral root, and every per-launch
profile directory mode 0700. A one-time chmod or ACL on a
directory that already exists does not cover the directory the next
launch creates, and an explicit mode at mkdir does not keep a
default ACL set on the parent. ProtectHome=yes also hides
/home until the unit drops it or adds ReadOnlyPaths= for the
tree. If file permissions cannot follow those new directories, the
connector user needs a capability such as CAP_DAC_READ_SEARCH to
read them. That capability lets the process read files its uid
could not otherwise read, which is wider than the port file. Do
not describe the separate-uid options as a finished install until
that is checked on a host.
If a host check shows the connector uid can see each new profile, the boundaries are the same kind of choice as the root-agent note above:
- The connector's uid is Hermes's uid. The tunnel credential
file is mode
0400owned by that user, so Hermes can read it, and so can a shell the model runs. The split between the agent and the credential is gone. The connector is also the owner of the browser profile, so it cannot be kept out of that profile. This is the option a live stock Hermes session has exercised. - Separate uid,
ProtectHome=yesremoved. The credential stays unreadable to Hermes. The connector can open every home path its file permissions and any capability allow, not only the DevTools file. - Separate uid,
ProtectHome=yeskept,ReadOnlyPaths=on the chromium cache tree. The credential stays unreadable to Hermes, and the rest of/homestays hidden. The connector can still read the throwaway profiles in that tree (cookies and page storage from the session), because those directories are where the port file lives. This is the narrower of the two cross-user options, and it still depends on the connector uid being able to read directories Hermes creates mode0700.
Since v0.3.0 (#235 phase 2), a dashboard Connect can also spawn the
connector. The dashboard's client metadata document must declare the
connector grant type; at consent the broker records that, and the
client redeems the extension grant for a connector token pair scoped
kharon:connector. The spawned connector's token_file then holds
the connector access token (kh_at_…) instead of a minted tunnel
credential — REQ-ARCH-002 makes a connector-audience kh_at_ a
tunnel credential on wire v1, and the broker enforces the audience at
authenticate time. The connector binary must be built from v0.3.0 or
later to accept that token file (#320). A connector token is refused
on /mcp (401): the two legs stay separate (#304).
A standalone agent host — one that does not arrive through a
dashboard — still uses the hand-provisioned path on this page: a
minted tunnel credential, a connector_token_hash in
[agents.<id>], and the file handed over out of band.
The install is done when the identity has a live session:
- The owner's Connections page shows the identity with a live browser session (and since when).
- From the agent side, an MCP
kharon_contextcall with the agent token returns the browser context id with statusok. Fills refuse until a session is live (REQ-OAU-007), so a refused fill with a "no browser attached" detail means the connector is not attached, whatever the MCP leg is doing.
Hermes Agent (Nous Research) drives its browser over CDP, so the
connector can share a browser Hermes is already attached to. The
stock path needs no browser.cdp_url and no port in
connector.toml (#337, #349). kharon does not launch the browser.
Hermes owns it and keeps driving it after a fill (REQ-ARCH-003).
The connector still dials loopback only. It adds no transport.
Hermes facts below are from its browser docs and from
NousResearch/hermes-agent main @ f578714 (2026-11-15), the
source pin from #337. hermes_constants.py
_platform_default_hermes_home is $HERMES_HOME or ~/.hermes.
tools/browser_launcher.py _ephemeral_root is
<home>/cache/browser/chromium, and _default_user_data_dir
creates a new directory under that root for each stock launch
(<digest>-<pid>-<start>). _read_devtools_file reads line 1 as
the port and line 2 as /devtools/browser/<id>. _make_browser
builds ws://127.0.0.1:<port><path>. The same three functions are
what the connector's preset implements. A Hermes home other than
the platform default (a profile under profiles/) is not inferred;
set hermes_home or HERMES_HOME for the connector process.
-
Leave Hermes on its stock local Chromium. Do not set
browser.cdp_urlorBROWSER_CDP_URL. Hermes launches with--remote-debugging-port=0and writes<user-data-dir>/DevToolsActivePort. The port changes every time that browser starts. -
Point the connector at the preset, not a port. Steps 3–8 above apply (
ptrace_scope, binary, tunnel credential file, MCP client), butconnector.tomlomitscdpandcdp_url:transport = "ws" broker_url = "wss://<host>/connector" broker_pin = "<64 hex chars>" agent_id = "<agent>" token_file = "/etc/kharon-connector/token"
With no explicit endpoint the connector scans
<hermes home>/cache/browser/chromium/*/DevToolsActivePortand dials127.0.0.1on the port in the newest file whose/json/versionbrowser id still matches line 2. One live Hermes browser per connector. Two concurrent Hermes sessions can leave the tab you want in the older browser while the connector dials the newer one, and the fill is thentarget_not_owned. Picking among several live browsers is a later change. It re-reads that tree on every CDP dial. A broker reconnect does not read the file until the next dial, and--checkdoes not read it at all. A missing, unreadable, truncated, or stale file fails that dial and the connector stays up. On a hand-provisioned agent the MCP tools report that aserror/cdp_error, not asno_browser. It never dials anything but loopback. The broker pin andagent_idchecks are unchanged.The home in that scan is the connector process's own
$HERMES_HOMEor$HOME/.hermes, not Hermes's home on another uid. On the documented connector unit (User=connector,ProtectHome=yes) that default does not see a stock Hermes profile. The setup checked on a stock Hermes host runs the connector as Hermes's user. A separate uid is described, and marked unchecked, in Hermes discovery and the connector user. The process logs the path it will scan at start (cdp: discover hermes_home=…).Override the preset when the browser is not in that home. Set one of these, not a combination:
Key What it reads hermes_home<path>/cache/browser/chromium/*/DevToolsActivePort.$HERMES_HOMEin the connector's environment is the same knob whenhermes_homeis unset.user_data_dir<path>/DevToolsActivePort, one Chromium profile. Use this forbrowser.user_data_dir.devtools_active_portThat file, exactly. -
Put the managed policy on the browser Hermes launches. The file from step 2 of the hosted-runtime list must be in that Chromium's policy directory. Hermes's packaged browser is Chrome for Testing, which reads
/etc/opt/chrome_for_testing/policies/managed/, not the Debianchromiumor Google Chrome directories named for the other builds. Without the file the browser may offer to save a filled password (REQ-ARCH-004). The host gets its own agent id (#281). Run--checkand start the connector as in step 7.--checkproves the broker leg; it does not require the browser to be up. Verify the install the same way as any other host:kharon_contextreturnsokwith a live session on the owner's Connections page.
Agents call kharon_open with the item id. kharon opens that item's
saved login URL in a new tab in the agent's browser and returns the
tab id and the live origin. kharon does not return or log the path,
query or fragment. The opened tab has the full URL, and whether the
model sees it is the harness policy (SPEC OQ-3). kharon_search
still returns only the host. On a build that does not have
kharon_open, put the login URL in the prompt. A fill after
kharon_open still needs the owner's grant.
Hermes has to open its browser first. kharon does not launch
the browser, and stock Hermes launches it only when its own browser
tool first runs. Before that, kharon_open and kharon_context
both return cdp_error. In the Hermes canary (#339) a model that
called them first stopped and reported the browser unreachable. Tell
the agent to open a page with its browser tool before it calls a
kharon tool that needs the browser.
kharon_open takes an item_id and nothing else. A model that has
not looked the item up may pass a URL and get bad_request; one
did on OpenClaw (#336). Tell the agent to call kharon_search or
kharon_list first.
Tab rule. #334 settled the tab rule for OpenClaw: a fill
targets the platform's own tab in the default browser context,
under allow_default_context with exactly one agent on the deploy
(see Which tab a fill uses). Hermes also
opens its tabs in the default context. The Hermes canary (#339, run
2026-11-18 on master 13b2d53) filled a tab Hermes had opened
itself, with the flag on, so the same rule holds on Hermes. That
run did not repeat the flag-off case on Hermes.
An explicit endpoint wins over discovery. Set cdp or cdp_url
(not both) and the connector dials that loopback socket and does
not read DevToolsActivePort. Use this when Hermes is attached to
a browser you started on a fixed port.
-
Start Chromium with
--remote-debugging-address=127.0.0.1 --remote-debugging-port=9222and a dedicated--user-data-dir(since Chrome 136 a debugging port on the default profile directory is ignored). Keep it running under a supervisor. Abrowser.cdp_urlpointing at a port where nothing is listening attaches to nothing. -
Point Hermes at it in
$HERMES_HOME/config.yaml:browser: cdp_url: "http://127.0.0.1:9222"
or set
BROWSER_CDP_URL=http://127.0.0.1:9222. Hermes resolves its CDP override in the order: a live/browser connect>BROWSER_CDP_URL>browser.cdp_url./browser connectis a CLI slash command only. A gateway, WebUI, or chat-platform session will not run it — the message goes to the model as text — so never write an install or a runbook that tells a gateway/WebUI operator to type it. Typed in the CLI with no argument it attaches tohttp://127.0.0.1:9222(or aws://URL passed to it), and if nothing is listening there it auto-launches a Chromium-family browser with--remote-debugging-port=9222and a dedicated user-data dir. That auto-launch lives only as long as the CLI session. For any non-CLI session,browser.cdp_url/BROWSER_CDP_URLis the attach mechanism. -
Name the same loopback port in
connector.toml. Either form works; a path oncdp_urlis ignored because the connector dials the port and the broker resolves/devtools/browser/<id>:cdp = "127.0.0.1:9222"
cdp_url = "http://127.0.0.1:9222"
http://andws://to127.0.0.1or::1are accepted. Any other host is refused. The examples use 9222; any free loopback port works if both sides use it.
- Cloud providers (Nous subscription, Browserbase, Browser Use, Firecrawl, another provider plugin). The browser is off the host; the connector dials loopback only.
- Lightpanda (
browser.engine: lightpanda). Not Chromium; kharon's fill path is Chromium CDP. browser_vault. Hermes's own login store and fill tool. kharon does not call it; the customer vault stays the Bitwarden collection on the broker.browser.use_real_profile. A Hermes-managed snapshot of the user's real profile. The stock preset does not scan it. Pointuser_data_dirat that profile if you want discovery there; otherwise it stays outside this install.
OpenClaw's managed profile is a Chromium that OpenClaw launches and
drives over CDP on a loopback port. The connector shares that
browser through an explicit cdp port. kharon does not launch a
browser here and adds no transport. OpenClaw keeps driving the
browser after a fill (REQ-ARCH-003), which the live runs below saw.
The canary (#336) also saw it keep the browser after the connector
stopped.
Where each statement comes from:
- Live run: #334's run on a fresh Debian 13 guest (pve VM 127),
OpenClaw 2026.11.3 (
847611d), profileopenclaw, driveropenclaw, Debianchromium156.0.8078.79 headless, a throwaway broker on a fixture vault. Tabs came fromopenclaw browser open, not a model-driven agent turn, because no model was configured. - Canary: #336's run on the same guest on 2026-11-18, with
kharond and the connector built from master
13b2d53and the owner approving by hand. It ran the steps #334 had left open, and one model-driven agent turn. The guest predates this section, so an install on a fresh guest from this text alone is still not run yet. - Source:
openclaw/openclawtagv2026.11.3(847611d) andmain@de40bf5c, underextensions/browser/src/. Where the two differ, this section says so.
- In: the managed
openclawdriver (the default profile, also namedopenclaw) on the same host as the connector. AlsoattachOnlyto a browser on that same host, when the connector dials the same loopback port. - Out:
driver: "extension"(the relay drives a signed-in Chrome; there is no CDP port to share, same family as #331),driver: "existing-session"(Chrome DevTools MCP; no stable raw CDP port), and a remotecdpUrl(Browserless, Browserbase, Browser Use and any other off-host browser). The connector dials loopback only.
The roadmap's OpenClaw section has the longer profile notes.
OpenClaw uses two loopback ports. Only one of them is CDP.
| Port | Default | What it is | The connector |
|---|---|---|---|
| Control port | 18791 (gateway.port + 2) |
OpenClaw's browser control service | Never dials it |
cdpPort |
18800, the first of 18800–18899 (control port + 9) | The managed Chromium's --remote-debugging-port |
cdp = "127.0.0.1:<cdpPort>" |
Both defaults are from extensions/browser/src/config/port-defaults.ts.
Creating a profile writes its chosen cdpPort into OpenClaw's
config, so read the port from there or from the running browser,
not from this table:
ps -eo args | grep -o -- '--remote-debugging-port=[0-9]*' | sort -u
ss -ltnp | grep '127.0.0.1:<cdpPort>'OpenClaw launches the browser with --remote-debugging-port, its
own --user-data-dir and no --remote-debugging-address
(browser/chrome.ts). Chromium's remote-debugging server then
binds 127.0.0.1 only (Chromium source, read on #334). The live
run saw exactly that (ss -ltnp: 127.0.0.1:18800).
browser.extraArgs is appended to that launch line. Do not put
--remote-debugging-address in it. A non-loopback bind exposes the
browser to the network, and the connector would still dial
127.0.0.1.
The managed policy has to go in the policy directory of the binary
OpenClaw actually runs. On Linux, OpenClaw 2026.11.3 picks
(browser/chrome.executables.ts):
browser.executablePath, when set.- Otherwise the desktop's default browser (
xdg-settings), if it is Chromium-family. - Otherwise the first that exists of Google Chrome
(
/usr/bin/google-chrome…), Brave, Microsoft Edge, Chromium (/usr/bin/chromium…), then a Playwright-cached Chromium.
So a host with Google Chrome installed runs Google Chrome, even when
Debian's chromium is also there. Pin the binary in OpenClaw's
config (~/.openclaw/openclaw.json by default) so the policy
directory can't change under you:
{
"browser": {
"executablePath": "/usr/bin/chromium"
}
}The #334 run had no browser block and got /usr/bin/chromium,
because nothing earlier in that order was installed. The canary
(#336) set the pin, and after a gateway restart
openclaw browser status reported that binary. The guest had no
other Chromium-family browser, so the pin overriding an earlier
entry in that order is not run yet.
-
OpenClaw and its managed profile. Install OpenClaw and leave the
openclawprofile on theopenclawdriver. Note itscdpPortand the browser binary, as above. Do not runprovision-connector.shas-is on this host: it installs and starts its ownbrowser.service, a second Chromium. -
The managed policy. Write the policy file from step 2 of the hosted-runtime list to the policy directory of the binary from the section above:
/etc/chromium/policies/managed/for Debian'schromium,/etc/opt/chrome/policies/managed/for Google Chrome. For any other binary, use that browser's managed-policy directory and rely on thechrome://policycheck, not on this page. The managed profile persists between launches, so this policy is the whole mitigation for saved passwords and form data there (post-fill exposure, rows C1 and C2). Then openchrome://policythrough CDP and look for the seven policies; restart OpenClaw's browser if they are missing. On the canary host (#336, Chromium 156) all seven were listed as Platform, Mandatory: five with status OK, andAutofillAddressEnabledandAutofillCreditCardEnabledwith statusDeprecated. -
Steps 3–8 of the hosted-runtime list:
ptrace_scope, the connector binary, the tunnel credential file,connector.toml, check and run, the MCP client. In step 6, setcdpexplicitly:transport = "ws" broker_url = "wss://<host>/connector" broker_pin = "<64 hex chars>" agent_id = "<agent>" token_file = "/etc/kharon-connector/token" cdp = "127.0.0.1:<cdpPort>"
Do not leave
cdpandcdp_urlout. With neither, the connector turns on the Hermes discovery preset and scans<hermes home>/cache/browser/chromium/, which OpenClaw never writes.--checkstill printscheck: ok, because it never dials the browser. Fills then fail witherror/cdp_error. An explicitcdpreads no file, so the connector can run as its own user without access to OpenClaw's home. The canary (#336) ran that layout: the connector as its ownconnectoruser, OpenClaw as another.For the MCP client, OpenClaw keeps servers under
mcp.serversin its config and substitutes${VAR}in header values from its environment, so the agent token stays out of the config file. The canary used:{ "mcp": { "servers": { "kharon": { "url": "https://<host>/mcp", "transport": "streamable-http", "headers": { "Authorization": "Bearer ${KHARON_AGENT_TOKEN}" } } } } }with
KHARON_AGENT_TOKEN=kh_agent_<id>_…in~/.openclaw/.env, mode0600. That file belongs to OpenClaw's user. Whether OpenClaw's tools refuse to read it was not tested, the same open question as Hermes's.env. A broker behind a private CA needsNODE_EXTRA_CA_CERTSin the gateway service's environment; the.envfile is read too late for that variable. A public edge does not need it. -
The broker. The host gets its own agent id (#281). In
kharon.toml, set[policy] allow_default_context = true
kharond refuses to start with this flag and more than one
[agents.*]entry (config/raw.rs), so this deploy serves exactly one agent. The reason is under Which tab a fill uses. -
The agent harness. Apply the agent harness policy as below.
What a root agent costs applies here too: if OpenClaw runs as root, the isolation goals don't hold.
Decided on #334, option (b): a fill targets a tab in the browser's
default context, the context OpenClaw opens its tabs in, with
allow_default_context = true and one agent on the deploy.
OpenClaw has no setting for a browser context and its agent tool
has no raw CDP action, so the agent can't open a tab in the context
kharon_context returns. This needs a kharon build that includes
#343 (master f393b00 or later). Before that fix, a
default-context tab on real Chromium was refused as
target_not_owned whatever the flag said (#342).
- Fills work on tabs OpenClaw's browser tool opens, and on tabs
kharon_openopens. With the flag on,kharon_opencreates its tab in the default context too, so OpenClaw can drive it.kharon_openreturns the target id. For a tab OpenClaw opened, the agent passes that tab's CDP target id as the fill'starget.cdp_target_id, withexpected_origin. Both were filled in the canary (#336): a tab fromopenclaw browser open, and akharon_opentab, whichopenclaw browser tabslisted like any other. - Fills do not work on tabs a session dashboard opens. OpenClaw
puts those in its own isolated context, and kharon refuses them
as
target_not_owned. Not run live; a stand-in (a tab in a context a second CDP client created) was refused that way. - With the flag off, a fill into OpenClaw's tab is
target_not_ownedand asks for no grant. In the live run a refusal before any grant was plaintarget_not_owned; the detaildefault_context_refusedonly appeared on a fill that already held a grant.
kharon_open is the way to reach the login page, as for Hermes.
kharon opens the item's saved login URL in a new tab and returns
only the tab id and the live origin, not the path, query or
fragment. The tab itself has the full URL, and whether the model
sees it is the harness policy (SPEC OQ-3). On a build without
kharon_open, put the login URL in the prompt. A fill after
kharon_open still needs the owner's grant.
Stock OpenClaw does not meet the agent harness policy out of the box. The operator has to close two gaps and tell the customer what stays open.
-
Page JavaScript.
act:evaluate(andwaitwith a function) is on by default (browser.evaluateEnabled, defaulttrue). Turn it off:{ "browser": { "evaluateEnabled": false } }OpenClaw then refuses those actions with a 403 (
routes/agent.act.ts). With the setting off, the canary (#336) sawopenclaw browser evaluaterefused withact:evaluate is disabled by config. The default-on behaviour is read from source. -
Snapshots. On OpenClaw 2026.11.3,
openclaw browser snapshotreturned a filled password in clear in the live run (textbox "Password": <value>). The canary (#336) counted matches in a snapshot written to a file: the defaultaiformat contained the filled password, and theariaformat did not in that run. Do not treatariaas a mitigation on one sample. OpenClaw'smainmasks password-type and credentialautocompletefields in snapshots as[redacted](da41e7de,browser/sensitive-field-values.ts), but no release has it as of 2026-11-15 (checked throughv2026.11.5-beta.3). Even with it, other field values, such as the username, still appear. Until a release with masking is installed, either keep the model away from snapshots while a filled login form is on the page, or fill withsubmit: true(fill_and_submit) so the form leaves the page as soon as it is filled, and tell the customer the model can read a filled value in the meantime. -
Screenshots. Not checked. The browser draws password inputs masked; the username shows.
kharon can't close these from its side: the value has to be in the page for the form to submit (SPEC §2.4).
Verify the install as for any host
(Verify the install): --check prints
check: ok, kharond logs agent connector attached, and
kharon_context returns ok with a live session on the owner's
Connections page. Then one fill: open a tab, kharon_fill returns
pending_approval, the owner approves, and the result is filled
with the fields holding the item's values.
The canary is #336: an approved fill into the managed browser,
then the connector stopped, OpenClaw still driving the same tab,
and the next fill refused. It ran on 2026-11-18. With the connector
stopped, OpenClaw focused, navigated and snapshotted the same tab
in the same Chromium process. The next kharon_fill returned
{"fields_filled":[],"status":"timeout"} after about 10 seconds,
and kharon_context returned {"status":"timeout"}. The roadmap
expects that refusal to be no_browser. A hand-provisioned agent
with its connector stopped shows up as timeout on OpenClaw and
on Hermes (#339; see
Hermes discovery and the connector user).
What to tell the agent. In the canary's one model-driven turn,
the model found kharon_open through OpenClaw's tool search before
it found kharon_search, passed a URL, got bad_request, and
stopped to ask the user for the item id. It finished the fill after
one message naming kharon_search and kharon_list. A prompt for
an OpenClaw agent should say: look the login up with
kharon_search, open it with kharon_open, ask for the fill, wait
for approval, and do not snapshot the page once it is filled.
kharond creates its browser context when it attaches. A kharond restart doesn't dispose the old one, so OpenClaw's Chromium keeps it: the live run listed five contexts, one live. They hold no tabs kharon opened under this install (fills use the default context) and go away when OpenClaw restarts its browser.
The tunnel credential and the agent token are each printed once, on the operator's terminal, by the mint command. From there they go to the runtime by one of these routes, in order of preference:
- The runtime's own secret setting. Many hosted runtimes have a
secrets or environment page that writes a value to a file or an
environment variable inside the runtime. The person who minted the
value pastes it there directly. For the tunnel credential, the
runtime's setup step then writes it to the token file at mode
0400(for exampleinstall -m 0400 /dev/stdin /etc/kharon-connector/tokenreading from that variable), and the variable is unset afterwards. - Encrypted to the runtime. The runtime generates a key pair
(for example
age-keygen -o /root/handover.key) and publishes only the public key. The operator encrypts the credential to it on the minting machine and sends the ciphertext any way they like; the runtime decrypts it straight into the token file (age -d -i /root/handover.key | install -m 0400 /dev/stdin /etc/kharon-connector/token) and deletes the key.installcreates the file at mode0400, the same way route 1 does. - The customer types it. When the customer has a terminal in
the runtime and the operator doesn't, the operator reads the value
to them over a call. The customer types it at a hidden prompt
straight into the token file, the way the canary is typed (#121):
( IFS= read -rs T; printf '%s' "$T" | install -m 0400 /dev/stdin /etc/kharon-connector/token; unset T ). That writes mode0400and skips an editor's swap and backup files. Slow, but nothing stores it in transit.
Never:
- paste a secret into a chat, an issue, a PR, Discord, or the agent's conversation, where the model or a log keeps it;
- put it on a command line or in a URL (argv shows up in
psand shell history); - commit it, or bake it into an image or a runtime template;
- reuse one credential for two agents.
broker_pin is not secret, so chat is fine, but a swapped pin points
the connector at someone else's broker. Send it one way and confirm
the first and last eight hex digits another way (a call, or the
owner UI).
| Step | Who |
|---|---|
Mint the agent token and the tunnel credential, put both hashes in [agents.<id>], restart kharond |
Operator, on the broker |
Compute and send broker_pin |
Operator |
| Steps 1–4 and 6–8 above | Whoever can install in the runtime |
| Step 5, and putting the agent token in the MCP client's secret setting | Whoever holds the value, by a route above |
If either secret may have been seen by anyone who shouldn't have it (a paste into chat counts):
- Agent token. On the broker,
kharon revoke agent <id>while kharond is running (durable; it also revokes the agent's grants). Mint a new token, replacetoken_hashin[agents.<id>], restart kharond, and hand the new token over by a route above. See Agent tokens. - Tunnel credential. Run
kharon tunnel mint <id>, replaceconnector_token_hashin[agents.<id>], and restart kharond; the old credential stops authenticating. Hand the new one over, write it to the token file, and restart the connector. - The runtime itself (root compromised, image leaked): rotate both, and if the agent may have read a filled value, treat that login's password as exposed and change it in the vault.