Overview

Fill from Vault is an integration path where your application or agent controls the login workflow. vaults store encrypted credential items. our fill api call writes selected values from an item into browser fields, without exposing secrets to your application or agent. your application or agent owns navigation, field selection, submission, and recovery. start with the end-user auth workflow cookbook for an end-to-end example of secure collection, browser attachment, the fill operation, form submission, and cleanup. KERNEL collects credential values from the user or accepts them from a trusted backend. when invoking fill, your controller sends field names and selectors rather than credential values. KERNEL reads the encrypted item and returns value-free outcomes, keeping stored secrets out of agent prompts and browser-automation payloads.

fill only writes stored values into fields you select. it doesn’t discover fields, navigate, submit forms, verify authentication, monitor the session, or reauthenticate. your application or agent owns each of those steps.

When to use it

Fill from Vault works best when:

a login or authentication prompt can appear in the middle of a workflow, in the same browser session.
your product needs to control the credential collection experience.
your application or agent already handles browser navigation and site-specific recovery.
you don’t need KERNEL to monitor the session or reauthenticate it automatically.

choose managed auth instead when you want KERNEL to run the login flow, save the authenticated state, monitor the connection, and attempt reauthentication for eligible flows.

How it works

these examples continue in order, using hacker news as the login destination. set KERNEL_API_KEY in your trusted backend environment. all examples use the default project; keep the vault and browser in the same project if you select a different one.

Create a Vault

create a vault for each end user or credential-sharing boundary. A vault groups the items that an attached browser session can use.

import Kernel from "@onkernel/sdk";

const kernel = new Kernel();
const vault = await kernel.vaults.upsert({ name: "user-12345" });

from kernel import Kernel

kernel = Kernel()
vault = kernel.vaults.upsert(name="user-12345")

VAULT_NAME="user-12345"
kernel vaults create --name "$VAULT_NAME"

Attach the Vault to a Browser

attach the vault when you create the browser. The attachment can’t change during the session and grants access to every item in that vault.

const browser = await kernel.browsers.create({ vaults: [{ id: vault.id }] });

browser = kernel.browsers.create(vaults=[{"id": vault.id}])

kernel browsers create --vault "$VAULT_NAME" -o json
read -r -p "paste the returned session_id: " BROWSER_ID

Navigate and Collect Credentials

your application or agent navigates to the login page and identifies its fields before defining a credential item. hacker news has both login and create-account forms; the selectors in the next step target the login form. inspect the page and recheck them if it changes.

await kernel.browsers.playwright.execute(browser.session_id, {
  code: "await page.goto('https://news.ycombinator.com/login'); return await page.title();",
});
const item = await kernel.vaults.items.upsert("hn-login", {
  id_or_name: vault.id,
  type: "credential",
  spec: {
    description: "Hacker News",
    fields: {
      username: { type: "text", required: true, sensitive: false },
      password: { type: "password", required: true, sensitive: true },
    },
  },
});
if (item.type !== "credential") throw new Error("expected a credential item");
const collectionURL = item.action?.url;
// Show collectionURL only to the intended user, not in general application logs.

kernel.browsers.playwright.execute(
    browser.session_id,
    code="await page.goto('https://news.ycombinator.com/login'); return await page.title();",
)
item = kernel.vaults.items.upsert(
    "hn-login",
    id_or_name=vault.id,
    type="credential",
    spec={
        "description": "Hacker News",
        "fields": {
            "username": {"type": "text", "required": True, "sensitive": False},
            "password": {"type": "password", "required": True, "sensitive": True},
        },
    },
)
if item.type != "credential":
    raise RuntimeError("expected a credential item")
collection_url = item.action.url if item.action else None
# Show collection_url only to the intended user, not in general application logs.

kernel browsers playwright execute "$BROWSER_ID" \
  "await page.goto('https://news.ycombinator.com/login'); return await page.title();"
kernel vaults credentials create "$VAULT_NAME" hn-login --spec-file - <<'JSON'
{
  "description": "Hacker News",
  "fields": {
    "username": {"type": "text", "required": true, "sensitive": false},
    "password": {"type": "password", "required": true, "sensitive": true}
  }
}
JSON

present the collection url only in the intended user’s authenticated interface or private conversation. don’t log it or open it in the agent-controlled browser. wait for the user to finish before continuing. an existing ready item may omit the collection action; reuse it or follow credential collection to reopen the form.

Invoke the Fill Operation

retrieve the same item, require readiness and an advertised fill operation, then invoke fill with field names and selectors. readiness means values exist, not that the website has accepted them. your application must authorize the destination before filling.

const current = await kernel.vaults.items.retrieve(item.key, {
  id_or_name: vault.id,
  wait: 60,
});
if (current.id !== item.id || current.type !== "credential" ||
    current.state.status !== "ready" ||
    !current.available_operations.some((operation) => operation.type === "fill")) {
  throw new Error("credential is not ready to fill");
}
const result = await kernel.vaults.items.performOperation(item.key, {
  id_or_name: vault.id,
  type: "fill",
  browser_id: browser.session_id,
  page_url: "https://news.ycombinator.com/login",
  fields: [
    { field: "username", selector: "form:has(input[autocomplete='current-password']) input[name='acct']" },
    { field: "password", selector: "input[autocomplete='current-password']" },
  ],
});
if (result.type !== "fill" || result.status !== "completed") {
  throw new Error("stop and reconcile the fill outcome");
}

current = kernel.vaults.items.retrieve(item.key, id_or_name=vault.id, wait=60)
if (current.id != item.id or current.type != "credential" or
        current.state.status != "ready" or
        not any(operation.type == "fill" for operation in current.available_operations)):
    raise RuntimeError("credential is not ready to fill")
result = kernel.vaults.items.perform_operation(
    item.key,
    id_or_name=vault.id,
    type="fill",
    browser_id=browser.session_id,
    page_url="https://news.ycombinator.com/login",
    fields=[
        {"field": "username", "selector": "form:has(input[autocomplete='current-password']) input[name='acct']"},
        {"field": "password", "selector": "input[autocomplete='current-password']"},
    ],
)
if result.type != "fill" or result.status != "completed":
    raise RuntimeError("stop and reconcile the fill outcome")

kernel vaults items get "$VAULT_NAME" hn-login --wait 60 -o json
# Continue only if the same item is ready and advertises fill.
kernel vaults items invoke "$VAULT_NAME" hn-login fill --spec-file - <<JSON
{
  "browser_id": "$BROWSER_ID",
  "page_url": "https://news.ycombinator.com/login",
  "fields": [
    {"field": "username", "selector": "form:has(input[autocomplete='current-password']) input[name='acct']"},
    {"field": "password", "selector": "input[autocomplete='current-password']"}
  ]
}
JSON

completed means the selected fields were filled, not that login succeeded. if fill fails, returns an uncertain outcome, or loses its response, stop and inspect the outcome rather than automatically retrying.

Submit and Handle the Response

after fill completes, your application or agent submits the login form once and verifies the site’s response. fill doesn’t perform either step. handle any additional authentication prompts before continuing the task.delete the demo browser when finished, and delete the vault only if you created it for this demo and no longer need its credentials. see the cookbook for the complete agent handoff and cleanup guidance.

Credential sources

you can collect values from an end user with KERNEL’s hosted collection form or copy them from an existing credential vault that your trusted backend can read. both paths produce a ready credential item and use the same fill operation. today, copying values stores an encrypted KERNEL copy. fill doesn’t accept raw values or a third-party vault reference in its request.

Session state

fill completes one part of the workflow. it doesn’t monitor the resulting session or reauthenticate it later. if you want to reuse the authenticated state, create the browser with a profile and save its changes after the login succeeds.

Next steps

Credential Items

define fields, collect values, and update credentials without returning sensitive values.

Fill Browser Fields

map credential fields to browser inputs and handle completed, failed, or unknown outcomes.

Build an End-User Auth Workflow

follow the complete collection and browser fill workflow with the sdk or cli.

Working with your browser

Integrations

Migrations

deploying your agent

Agent Skills

Community

Info

Overview

When to use it

How it works

Credential sources

Session state

Next steps

Credential Items

Fill Browser Fields

Build an End-User Auth Workflow

​When to use it

​How it works

​Credential sources

​Session state

​Next steps

Credential Items

Fill Browser Fields

Build an End-User Auth Workflow

When to use it

How it works

Credential sources

Session state

Next steps