kernel-auth

Kernel Auth

use a managed auth connection to acquire a reusable authenticated browser profile, or a vault credential to sign in from the agent's own browser, then continue the original website task with the browser-control method that fits it. this skill owns authentication and the handoff to an authenticated browser; it does not assume the task is qa.

decide whether authentication is needed

make this decision before listing or creating managed-auth connections or vault credentials:

1. treat a url as a resource identifier, not as evidence that the task requires browser access.
2. for structured reads and writes, prefer authoritative local records or a dedicated, service-specific api, cli, mcp server, or other first-party integration when it supports the operation. search the host's tool catalog, including deferred mcp tools, before concluding that no integration is available.
3. choose a browser only when the task genuinely requires the authenticated website ui, the dedicated integration lacks the needed capability, or browser behavior itself is under test.
4. after choosing a browser, start hosted login only when the target operation requires authenticated state. public or unauthenticated pages should not trigger managed auth.

if a dedicated integration can complete the task, use it and do not continue with this skill. if the decision selects an authenticated browser path, choose managed auth or vault credentials below; authenticated browser tasks must still use one of them.

choose managed auth or vault credentials

	managed auth	vault credentials
who runs the login	KERNEL, in its own temporary browser	the agent, in its current browser
result	a reusable authenticated profile	a signed-in task browser; save it to a profile if needed
recovery	health checks and eligible automatic reauthentication	the agent signs in again when needed
fits	unattended or recurring work on known sites	an end user who is present, or a login prompt mid-task

use managed auth when KERNEL should own the login lifecycle; follow the workflow below. use vault credentials when the agent must sign in within its own browser session; follow vault credentials. if an authenticated managed-auth profile already exists for the site, reuse it before creating a vault credential.

browser handoff model

a managed-auth login runs in its own temporary browser. it does not take over or authenticate an existing task browser in place. if an ordinary browser encounters a login wall:

1. pause all automation against that task browser. its page and live view may continue to show the logged-out site while managed auth advances elsewhere.
2. start one managed-auth flow and keep all authentication interactions attached to that flow until it completes.
3. follow or wait on the active flow. do not call login to poll: another login call supersedes the current flow.
4. after flow_status=SUCCESS and status=AUTHENTICATED, create a new ordinary browser from the connection's saved profile, attach the existing browser-control stack to that new session, and resume the task. switch any live view to the new task browser.

the original task browser's transient page state does not move into the managed-auth browser or the replacement profile-backed browser. preserve the target url and any task state needed to resume, and delete the old task browser when it is no longer needed.

core workflow

1. scope resources to the intended KERNEL project and identify the canonical site, current hostname, target url, account context, and any task state needed after authentication.
2. list every connection for the exact domain, following pagination. if none matches, inspect connections for the same profile and account before creating another: a site may redirect among sibling, tenant, or dedicated login hostnames. reuse a known connection id when the account context is unambiguous; do not assume arbitrary sibling subdomains belong to the same account.
3. if no relevant connection exists and the selected browser operation requires authentication, create one with a concise, stable profile name. a request to perform a task that clearly requires the user's site account is consent to check authentication; do not ask a redundant preliminary question.
4. if the connection is AUTHENTICATED, create a browser from its profile and verify by loading the target page. do not keep using an unprofiled task browser. a stale status or redirect to login requires reauthentication.
5. if the selected browser operation requires authentication and no valid authenticated profile is available, call login once, expose the hosted url through the host's user-visible mid-turn message mechanism, and immediately wait for the login in the same turn. do not end the task or require the user to reply before waiting.
6. continue waiting until flow_status=SUCCESS and status=AUTHENTICATED. if the flow expires, start a replacement flow, publish the new url mid-turn, and resume waiting.
7. create a new ordinary browser from the verified profile with browser telemetry enabled. preserve any proxy required by the connection.
8. continue the original task with whichever browser agent or control framework is already appropriate. reuse the existing browser-agent stack by attaching it to the new authenticated session; managed auth does not require switching to Playwright or KERNEL-native controls. use semantic automation for structured control and assertions, and computer actions when actual pointer, keyboard, focus, selection, drag, compositor, or visual behavior matters.
9. delete temporary and superseded task browsers when finished. retain a reusable connection and profile unless the user asked for disposable authentication.

if KERNEL mcp tools are available, prefer their typed operations: list/create/login/wait with the managed-auth tool, create/delete with the browser tool, Playwright for dom-level control, and computer actions for os-level input. use the cli workflow below as the fallback or when cli-specific functionality is needed.

safe defaults

1. set KERNEL_PROJECT once or pass global --project <id-or-name> to every command.
2. reuse an existing connection for the same domain, account, and profile instead of creating duplicates.
3. prefer credential references over putting secrets in command arguments, logs, chat, or shell history.
4. treat hosted, live-view, and cdp urls as sensitive. suppress link unfurls and never expose them beyond the intended user.
5. keep profile downloads outside repositories; they can contain cookies and authenticated browser state.
6. delete temporary browsers and downloaded state. do not delete a reusable connection or profile as routine cleanup or recovery.

check for an existing connection:

kernel auth connections list \
  --domain example.com \
  --profile-name example-main \
  -o json

create a connection

a connection requires a domain and profile name. KERNEL creates the profile automatically if it does not exist.

CONNECTION_ID=$(
  kernel auth connections create \
    --domain example.com \
    --profile-name example-main \
    -o json | jq -r '.id'
)

add only settings required by the site:

kernel auth connections create \
  --domain example.com \
  --profile-name example-main \
  --login-url https://example.com/login \
  --allowed-domain auth.example.com \
  --credential-name example-credential \
  --proxy-id prx_123 \
  --health-check-interval 3600 \
  --telemetry=console,network \
  -o json

important creation behavior:

• repeat --allowed-domain for non-standard redirect domains. common sso provider domains are allowed automatically.
• use either --credential-name or --credential-provider, not both.
• with --credential-provider <provider>, omit --credential-path to enable provider lookup by domain automatically. use --credential-path <path> to select a specific external item.
• prefer --proxy-id over --proxy-name for a stable, unambiguous reference.
• credentials are saved after successful login by default; --no-save-credentials disables this and usually prevents unattended reauthentication.
• health checks and automatic reauthentication default on server-side. the health-check interval defaults to one hour; accepted minimums depend on the organization's plan.

a connection's domain and profile cannot be changed with update; create another connection when either must differ.

update a connection

updates are partial except where noted:

kernel auth connections update "$CONNECTION_ID" \
  --login-url https://example.com/sign-in \
  --health-check-interval 3600 \
  --save-credentials \
  -o json

non-obvious update behavior:

• --allowed-domain replaces the entire allowed-domain list; repeat it with every domain to retain.
• pass --login-url '' to clear a custom login url.
• when changing to an external provider's domain lookup, pass both --credential-provider <provider> and --credential-auto. unlike create, update does not infer auto lookup.
• use either --save-credentials or --no-save-credentials.
• a telemetry category list merges those categories into the connection's existing config for future managed-auth sessions.

inspect the result after every update:

kernel auth connections get "$CONNECTION_ID" -o json | jq '{
  id,
  domain,
  profile_name,
  status,
  flow_status,
  flow_step,
  can_reauth,
  can_reauth_reason,
  health_checks,
  health_check_interval,
  browser_telemetry
}'

start and complete a login

start a login or reauthentication flow with the existing connection:

kernel auth connections login "$CONNECTION_ID" -o json

the response tells you whether KERNEL started a LOGIN or REAUTH flow and includes hosted_url, live_view_url, and flow_expires_at. the live_view_url belongs to the managed-auth browser, not any ordinary browser that triggered the login. custom interfaces must keep the rendered live view and submitted interaction state bound to this active flow.

when a human must act, publish hosted_url as a user-visible mid-turn message such as:

login is needed to continue: <hosted_url>. i will continue automatically when it completes.

keep the current turn active and begin following or waiting immediately after publishing the message. do not put the url only in the final response, ask the user to reply after login, or split the original task into a separate run. suppress link unfurls and do not expose the live-view or cdp url unless the intended user needs it.

track the flow until it reaches a terminal state:

kernel auth connections follow "$CONNECTION_ID"

with a typed tool that offers bounded long-polling, repeatedly call its wait action until success, failure, or expiry. preserve any returned flow checkpoint unchanged between calls. do not infer completion from a successful submit or one non-terminal wait response.

or poll the current state and canonical prompts:

kernel auth connections get "$CONNECTION_ID" -o json | jq '{
  status,
  flow_status,
  flow_step,
  flow_expires_at,
  fields,
  choices,
  external_action_message,
  website_error,
  error_code,
  error_message
}'

when flow_step is AWAITING_INPUT, prefer the canonical ids returned in fields and choices:

# Submit one or more fields as one submit mode.
kernel auth connections submit "$CONNECTION_ID" \
  --field-value 'field_email=<value>' \
  --field-value 'field_password=<value>'

# Or select exactly one returned choice.
kernel auth connections submit "$CONNECTION_ID" \
  --choice-id 'choice_sms'

use exactly one submit mode per call. do not combine canonical fields, a canonical choice, or any legacy selector in the same call. --field is legacy; use --field-value when fields is present. legacy-only flows may still require one of:

kernel auth connections submit "$CONNECTION_ID" --mfa-option-id sms
kernel auth connections submit "$CONNECTION_ID" --sign-in-option-id '<id>'
kernel auth connections submit "$CONNECTION_ID" --sso-provider google
kernel auth connections submit "$CONNECTION_ID" --sso-button-selector '<xpath>'

a successful submit means the input was accepted for processing, not that authentication has completed. wait for flow_status=SUCCESS and status=AUTHENTICATED.

do not call login again while the current flow is non-terminal; use follow, wait, or get to observe progress. a new login supersedes the active flow and can invalidate input the user was about to submit. if a stale flow is past flow_expires_at, call login again to replace it. do not delete the connection or profile just to refresh an expired flow.

telemetry

configure telemetry when creating a connection, updating defaults for future managed-auth sessions, or overriding one login:

# Reset to the default telemetry categories.
kernel auth connections update "$CONNECTION_ID" --telemetry=all

# Disable telemetry.
kernel auth connections update "$CONNECTION_ID" --telemetry=off

# Enable selected categories on future managed-auth sessions.
kernel auth connections update "$CONNECTION_ID" --telemetry=console,network,page

# Override only this login; the override merges onto the connection config.
kernel auth connections login "$CONNECTION_ID" --telemetry=screenshot,network

settable categories are console, network, page, interaction, control, connection, system, screenshot, and captcha. all means the default category set, not every category. a category list on create selects that list; on update it merges into the current selection. to remove selected categories, reset with off, then enable the desired set in a second update.

browser telemetry is opt-in and cannot backfill an earlier failure. connection telemetry applies only to managed-auth sessions, so enable telemetry again when creating every ordinary profile-backed browser. for authenticated work that the agent may need to monitor or diagnose, capture the site-facing categories from the start:

kernel browsers create \
  --profile-name example-main \
  --telemetry=console,network,page,interaction \
  -o json

all means KERNEL's default operational set and omits the debug-critical console, network, and page categories. telemetry can contain sensitive site metadata; enable only what the task needs and do not paste raw events into chat or repositories. when a browser fails or behaves unexpectedly, load the debug-browser-session skill for event retrieval, category selection, telemetry gaps, and post-delete inspection.

diagnose reauthentication

do not infer reauthentication readiness from status alone:

kernel auth connections get "$CONNECTION_ID" -o json | jq '{
  status,
  can_reauth,
  can_reauth_reason,
  auto_reauth,
  health_checks,
  health_check_interval,
  credential,
  save_credentials
}'

automatic reauthentication requires scheduled health checks, automatic reauth enabled, and a feasible credential or recorded login plan. can_reauth=false means a human action is currently required; inspect can_reauth_reason rather than repeatedly restarting the flow. common blockers include no prior successful login, no credential, no viable plan, external action, or an unavailable totp/sms/email code.

for a connection in NEEDS_AUTH:

1. attach or correct its credential reference with update when one is available.
2. call login on the existing connection.
3. complete any canonical fields, choices, or external action.
4. confirm status=AUTHENTICATED and can_reauth=true.
5. check the timeline for subsequent health-check or reauth outcomes.

inspect the timeline

timeline events are ordered most recent first:

kernel auth connections timeline "$CONNECTION_ID"
kernel auth connections timeline "$CONNECTION_ID" --type reauth
kernel auth connections timeline "$CONNECTION_ID" --type health_check --page 1 --per-page 50

json output is an object containing events, page, per_page, and has_more:

kernel auth connections timeline "$CONNECTION_ID" -o json |
  jq '.events[] | {timestamp, type, status, step, browser_session_id, error_code, error_message, website_error}'

use login events for human/initial attempts, reauth for automatic or subsequent authentication attempts, and health_check to see when session validity changed between AUTHENTICATED and NEEDS_AUTH.

use the authenticated browser

create an ordinary browser from the authenticated profile with telemetry enabled. add stealth, a proxy, profile saving, or a longer timeout only when the site or task needs them:

kernel browsers create \
  --profile-name example-main \
  --start-url https://example.com/account \
  --telemetry=console,network,page,interaction \
  -o json

load the target page and verify authenticated state before doing consequential work. if the page redirects to login, reauthenticate the existing connection rather than creating another profile.

choose controls based on the task:

• if the task already uses a browser agent or automation framework, keep using it and attach it to the authenticated browser through its supported session or cdp integration. do not switch control stacks solely because authentication came from KERNEL.
• use Playwright for navigation, semantic locators, dom state, extraction, and repeatable assertions.
• use computer actions for real mouse and keyboard input, caret/focus behavior, text selection, drag and drop, native dialogs, compositor behavior, or visual reproduction. end action batches with a screenshot when the interface supports it.
• combine them when useful: use Playwright to reach and inspect a state, computer actions to reproduce real input, then Playwright and telemetry to verify the result.
• use a site-specific or qa skill for domain logic or test planning; this skill remains responsible for authentication, profile reuse, and the browser handoff.

delete the temporary browser when finished. telemetry captured before deletion remains available for later inspection:

kernel browsers delete <browser-id-or-name>

rename or download profile state with the current profile commands:

kernel profiles update example-main --name example-primary -o json

PROFILE_DIR=$(mktemp -d)
kernel profiles download example-primary --to "$PROFILE_DIR" --format tar.zst
# Inspect locally; never commit the extracted state.
rm -rf "${PROFILE_DIR:?}"

--format accepts tar.zst (default) or tar; both are extracted into --to. if the profile has no saved data yet, download reports that it must first be used in a browser session.

cleanup temporary setup

deleting a connection terminates its workflow and cancels any in-progress login. it is separate from deleting the profile:

kernel auth connections delete "$CONNECTION_ID"   # confirm interactively
kernel profiles delete example-main                # only if its saved state is disposable

use --yes only in automation after verifying the exact connection id or profile name. never delete a reused authenticated profile as routine reauthentication recovery.

vault credentials

a vault holds one end user's credentials. name it after that user (for example user-123) and never mix unrelated users in one vault. vaults store credentials, not browser sessions: attach the vault when creating the browser, because the binding cannot change later. if the signed-in state must persist, also pass --save-changes with a per-user --profile-name that matches the vault's user (for example user-123). a shared profile would give other users one user's cookies.

two credential paths

every credential follows one of two paths. use these names with the user:

1. KERNEL-hosted collection (provider: "kernel"): the user enters values in a KERNEL-hosted form, and the agent uses them through value-free bindings without seeing them.
2. 1Password brokered approval (provider: "1password"): the user connects their 1Password account once and approves each login request in the 1Password app. the 1Password extension fills and submits, and KERNEL stores no login values. it supports only logins in the owner's own non-shared vault, not shared-vault items or passkeys.

choose the path in this order:

1. list the vault's items and reuse an existing credential for the site: a ready kernel credential, a ready 1password credential whose requested websites match, or a connected 1Password credential_account for a new 1password credential.
2. otherwise ask the user where their login lives and wait for the answer. do not choose for them. for example: "is your example.com login saved in your own 1Password, or would you rather enter it in a secure KERNEL form?" state the non-shared-vault and no-passkey limits when offering 1Password.
3. if 1Password is unavailable, the account can't be connected, the owner declines, or the login is in a shared vault or uses a passkey, tell the user and offer KERNEL-hosted collection. do not switch paths without asking. if the user wants neither, stop.

tools

with KERNEL mcp tools:

tool	actions	use
manage_vaults	create, list, get, delete	create or reuse the per-user vault
manage_vault_credentials	create, update, connect_account	define a credential, update KERNEL-hosted values, or connect a 1Password account
manage_vault_items	list, get, invoke, events, delete	read state and available_operations, invoke an advertised operation, and observe events

manage_vault_items invoke operations:

operation	path	effect	approval
collect	KERNEL-hosted collection	returns or reopens the collection form without clearing values	explicit user approval
fill	KERNEL-hosted collection	writes named fields into an ordinary web form; never submits	explicit user approval
webmcp_invoke	KERNEL-hosted collection	binds credential fields to null input slots of a live webmcp tool; the tool may submit or have other side effects	explicit user approval
1pw_create_access_request	1Password brokered approval	asks 1Password for access and returns the approval link; needs no browser	explicit user approval
1pw_access_request_status	1Password brokered approval	reads the owner's decision; needs no browser	none
1pw_fill	1Password brokered approval	the 1Password extension fills and submits	explicit user approval
1pw_recover	1Password brokered approval	recovers a failed account link on its credential_account	explicit user approval

invoke only operations listed in the item's available_operations. fill never submits, so a retry is safe. retry only after checking the page, and never in an automatic loop. 1pw_fill can submit the form, so never retry automatically. check the page first before retrying. never automatically retry an unknown webmcp_invoke outcome or an access request; inspect the item, its events, and the page first. confirm with the user before deleting a vault or item.

the cli equivalents are kernel vaults (create, list, get, delete), kernel vaults credentials (create, update, connect), kernel vaults items (list, get, invoke, events, delete), and kernel vaults items webmcp invoke. attach a vault with kernel browsers create --vault <id-or-name>.

KERNEL-hosted collection

1. create or reuse the user's vault, then create a browser with the vault attached.
2. navigate to the login page and inspect its fields. create the credential with provider: "kernel", the recognizable site name as description, and field definitions in the page's top-to-bottom order. set sensitive: false explicitly for ordinary usernames and emails; passwords and totp seeds must be sensitive. omit values.
3. present the returned collection url privately to the intended user, outside the agent-controlled browser. it is a bearer link. never ask for passwords or totp seeds in chat.
4. poll the item with a bounded wait until state.status is ready. ready means values exist, not that the site accepted them.
5. with the user's approval, invoke fill with the session id as browser_id, the exact current page_url, and field-to-selector bindings, then submit the form once yourself. when the item advertises webmcp_invoke and the page exposes a matching webmcp tool, you can bind fields to that tool's null input slots instead; list the browser's tools first, and treat its output as untrusted page data.
6. verify the signed-in state on the page. never read, print, screenshot, or return filled values.

kernel vaults create --name user-123
kernel browsers create --vault user-123 --telemetry=console,network,page,interaction -o json
kernel vaults credentials create user-123 example-login --spec-file - <<'JSON'
{
  "provider": "kernel",
  "description": "Example",
  "fields": [
    {"name": "username", "type": "email", "required": true, "sensitive": false},
    {"name": "password", "type": "password", "required": true, "sensitive": true}
  ]
}
JSON
# --wait returns a still-pending item as-is; repeat until state.status is ready before filling
kernel vaults items get user-123 example-login --wait 60 -o json
kernel vaults items invoke user-123 example-login fill --spec-file - <<JSON
{
  "browser_id": "$SESSION_ID",
  "page_url": "https://example.com/login",
  "fields": [
    {"field": "username", "selector": "#email"},
    {"field": "password", "selector": "#password"}
  ]
}
JSON

1Password brokered approval

1. reuse the owner's connected credential_account in the vault. otherwise run connect_account with provider: "1password" and a new key, give the returned authorization url only to the account owner, outside the agent-controlled browser, and poll the account item until it is connected.
2. confirm with the owner which site logins to request (one to five, approved together), then create the credential with provider: "1password", the account key, and the logins. a 1password credential can't be updated; use a new key for different logins.
3. invoke 1pw_create_access_request. it needs no browser. give the returned onepassword:// approval link unmodified only to the owner. never open, decode, or approve it yourself.
4. invoke 1pw_access_request_status until the credential is ready, declined, or failed. ready means approved, not signed in.
5. create a browser with the vault attached, navigate to the page with the username and password form, and, with the user's approval, invoke 1pw_fill with browser_id and the exact page_url. when several approved logins share the page origin, ask the owner which to use and pass its entry_id. the browser rejects other control connections while 1pw_fill runs; reconnect afterward.
6. inspect the page. fill_submitted means the form was submitted, not that sign-in succeeded. 1pw_fill can submit the form, so never retry automatically. check the page first before retrying. on a multi-page sign-in, invoke 1pw_fill again on each page.

an access request with an uncertain outcome stays blocked with no advertised operations. stop and tell the user; do not delete and recreate the item on your own to retry it. credentials backed by a developer-supplied 1Password access token are managed through the KERNEL api, not through the agent; never ask for or accept those secrets in chat.

the 1Password credential provider used by managed auth connections (--credential-provider, manage_credential_providers) is a separate service-account integration. it is unrelated to 1Password brokered approval.