Fill Browser Fields

invoke an item’s fill operation to write selected values into an attached browser. your request contains field names and css selectors, not credential values. the result reports outcomes without returning the values.

fill writes real values into the browser. page scripts, extensions, devtools, and an agent with unrestricted browser access may read them.

Check availability

retrieve the item and require fill in available_operations. KERNEL rechecks eligibility when you invoke it.

item	requirements
`credential`	ready, with a stored value for every requested field

attach the vault when creating the browser. the browser and vault must belong to the same project, and the attachment can’t change later. attaching a vault grants access to all its items, including items added later; use separate vaults for tasks that must not share credentials.

Map fields to inputs

the following examples continue with a kernel client, a per-user vault such as user-12345, and a browser attached to that vault. loginURL / login_url is the exact current url of a login page you control; the selectors match that page’s inputs.

const item = await kernel.vaults.items.retrieve("portal-login", {
  id_or_name: vault.id,
});
if (!item.available_operations.some((operation) => operation.type === "fill")) {
  throw new Error("fill is unavailable");
}
const result = await kernel.vaults.items.performOperation(item.key, {
  id_or_name: vault.id,
  type: "fill",
  browser_id: browser.session_id,
  page_url: loginURL,
  fields: [
    { field: "username", selector: "#username" },
    { field: "password", selector: "#password" },
  ],
});
if (result.type !== "fill" || result.status !== "completed") {
  throw new Error("stop and reconcile the fill outcome before continuing");
}

item = kernel.vaults.items.retrieve("portal-login", id_or_name=vault.id)
if not any(operation.type == "fill" for operation in item.available_operations):
    raise RuntimeError("fill is unavailable")
result = kernel.vaults.items.perform_operation(
    item.key,
    id_or_name=vault.id,
    type="fill",
    browser_id=browser.session_id,
    page_url=login_url,
    fields=[
        {"field": "username", "selector": "#username"},
        {"field": "password", "selector": "#password"},
    ],
)
if result.type != "fill" or result.status != "completed":
    raise RuntimeError("stop and reconcile the fill outcome before continuing")

field is a declared credential field name. a totp field writes a generated code, never its seed. format isn’t accepted for credentials.

Select the page and elements

page_url must exactly match one current top-level page, including path, query, and fragment. it isn’t a navigation instruction or a prefix match. credentials can omit it only when the browser has exactly one open page. credential items have no destination allowlist. your trusted controller must authorize the destination before disclosing credentials; neither description nor page_url grants or restricts that permission. each selector must identify exactly one editable input or select across the main frame and all descendant frames. a selector may identify a container only if it resolves to one unique editable element inside it. zero matches, multiple matches, or two bindings targeting the same element fail validation. selects match option values, not labels. KERNEL validates bindings before writing, then fills in request order. if navigation or a disappearing target interrupts filling, it stops instead of choosing a different page or element. timeout_ms is the total operation deadline, not a timeout per field; it defaults to 10,000 and accepts 1–30,000 milliseconds.

Handle the outcome

result	next action
`completed`	all fields were filled; inspect the page and decide whether to submit
`failed`	inspect the per-field outcomes; earlier writes aren’t rolled back
`unknown`	stop and reconcile; at least one field’s outcome can’t be determined
transport error	treat the outcome as uncertain because writes may already have happened

known execution failures can return http 200 with a failed or unknown status. inspect the response body, not only the http status. each entry in fields identifies its request binding by zero-based index and reports filled, failed, unknown, or not_attempted. bindings after the first failed or unknown field are not_attempted. fill doesn’t click buttons or submit forms, but input/change handlers can trigger site behavior. completed doesn’t mean login succeeded or a form was submitted. don’t automatically retry fill after a failure or uncertain outcome. a lost response can follow successful writes; another request can repeat events, overwrite edits, or generate a different totp code. deliberate recovery starts with inspecting the existing attempt, not replaying it. for the full application and agent handoff, follow use vault credentials in a browser agent.

Overview

Working with your browser

Integrations

Migrations

deploying your agent

Agent Skills

Community

Info

Fill Browser Fields

Check availability

Map fields to inputs

Select the page and elements

Handle the outcome

​Check availability

​Map fields to inputs

​Select the page and elements

​Handle the outcome

Check availability

Map fields to inputs

Select the page and elements

Handle the outcome