> ## Documentation Index
> Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-mcp-vault-tools-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Fill Browser Fields

> Safely inject vault values into browser fields without passing them through your application or model

`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](/auth/fill-from-vault). for an online checkout workflow that uses this api, see [Payments](/browsers/payments). `fill` also supports other eligible vault items; it isn't specific to authentication or a wallet provider.

<Warning>
  `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.
</Warning>

## 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.

`fill` is safe to retry. it only writes field values and never submits the form, so default sdk retries and your own retry loops are fine.

<a id="map-credential-fields-to-inputs" />

## 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.

<Note>
  `fill` reads values from a ready credential item. if another vault
  is your source of truth, [copy its values into a KERNEL credential
  item](/vaults/existing-credential-vault) first. today,
  this stores an encrypted copy in KERNEL; `fill` doesn't accept credential
  values or a third-party vault reference in its request.
</Note>

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.

<CodeGroup>
  ```typescript TypeScript theme={null}
  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("fill did not complete; inspect per-field outcomes and retry");
  }
  ```

  ```python Python theme={null}
  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("fill did not complete; inspect per-field outcomes and retry")
  ```
</CodeGroup>

`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`. use the per-field statuses to decide what to fix before retrying. 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, fix the cause, and retry; earlier writes aren't rolled back |
| `unknown` | retry; at least one field's outcome can't be determined |
| transport error | retry; 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.

**`fill` is safe to retry after a failure, an `unknown` outcome, or a lost response.** it never submits the form, so a retry only rewrites the same fields, and a `totp` field gets a fresh code. a retry right after an `unknown` result can wait up to 15 seconds for the earlier attempt's browser lock to expire. when a field `failed`, fix its cause, such as a selector that matched nothing, before retrying.

## Related guides

* [use vault credentials in a browser agent](/browsers/use-vault-credentials-in-browser-agent) for the full application and agent handoff.
* [payments on KERNEL](/browsers/payments) for using vault items in checkout.
* [link card requirements](/integrations/wallets/stripe-link#fill-the-checkout) for card fields and merchant restrictions. [agentcard](/integrations/wallets/agentcard) uses an alias-based flow instead of `fill`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.