Fill Browser Fields

fill is KERNEL’s api for safely injecting stored vault values into browser fields without passing those values through your application’s code or the model’s context. you supply an item reference, browser, and field selectors. KERNEL reads the stored values, checks the browser attachment and item lifecycle, validates the target inputs, and writes the values. the api returns per-field outcomes, not the injected values. unlike retrieving a secret and passing it to a browser library’s typing method, fill doesn’t require raw values in your request. your agent can identify fields and propose selectors while your trusted controller authorizes the destination and invokes the operation. for an authentication workflow using this api, see Fill from Vault. for an online checkout workflow that uses this api, see Payments. fill also supports other eligible vault items; it isn’t specific to authentication or a wallet provider.

fill writes real values into the browser. page scripts, extensions, devtools, and an agent with unrestricted browser or cdp access may read them. don’t assume recordings or other browser observation surfaces exclude filled values.

Check availability

retrieve the item and require fill in available_operations. KERNEL rechecks eligibility when you invoke it. the item must be ready and contain a stored value for each requested field. additional eligibility rules depend on the item and its provider; don’t assume every item supports fill. 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 items. use the browser’s session id in browser_id, not its name. KERNEL rechecks the attachment and item lifecycle before writing. configure your sdk client with maxRetries: 0 (typescript) or max_retries=0 (python) for fill, and don’t wrap it in a retry loop. the cli does not automatically retry fill requests.

Map fields to inputs

your request names the item and vault, the attached browser’s browser_id, the current page_url, and field-selector bindings. field names come from the item’s schema; they are not raw values. the following example uses a credential item with username and password fields.

fill reads values from a ready credential item. if another vault is your source of truth, copy its values into a KERNEL credential item first. today, this stores an encrypted copy in KERNEL; fill doesn’t accept credential values or a third-party vault reference in its request.

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") throw new Error("unexpected operation response");
console.log(result.status, result.fields);
if (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":
    raise RuntimeError("unexpected operation response")
print(result.status, result.fields)
if 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

when supplied, 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. zero or multiple matching pages fail. credentials: omit page_url 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

the cli exits nonzero for failed or unknown, but retains the value-free result on stdout with -o json. preserve that output and its per-field statuses; don’t discard it or retry just because the exit code is nonzero. a transport error can leave the outcome uncertain even without a result body.

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, a form was submitted, or payment succeeded. 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. preserve per-field index, status, and any error_code for reconciliation.

use vault credentials in a browser agent for the full application and agent handoff.
payments on KERNEL for using vault items in checkout.
link card requirements for card fields and merchant restrictions. agentcard uses an alias-based flow instead of fill.

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

​Related guides

Check availability

Map fields to inputs

Select the page and elements

Handle the outcome

Related guides