# Browser passwords



Agents can hold encrypted browser login records — a username and password for a
given HTTPS origin — scoped to a Computer's [environment](/docs/agents/environments).
These routes manage the records; they are not agent tools. Native browser
save and fill inside the Computer is an opt-in path still being rolled out: it
receives one selected login only through a short-lived, Computer-bound grant,
and the agent itself never sees secret values. There is no owner or model
plaintext readback endpoint, and records are never returned with their secret
values.

## Ownership [#ownership]

A password record belongs to the authenticated caller, the environment's
organization, and the environment itself. It survives replacement of the
environment's backing VM, but is not carried over to a different environment.
An organization member cannot see another member's passwords, and the
environment must be active (not archived) to manage its passwords.

## Save, list, and delete [#save-list-and-delete]

```bash
# Create — the client generates the UUID and sends expected_revision: 0
curl -X PUT https://agents.clusterbase.dev/v1/environments/env_9a8b7c/browser-passwords/1c9b7b2e-... \
  -H "Authorization: Bearer $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_revision": 0,
    "origin": "https://example.com",
    "display_name": "Example login",
    "username": "alice",
    "password": "correct-horse-battery-staple"
  }'
# → { "id": "1c9b7b2e-...", "origin": "https://example.com", "display_name": "Example login", "revision": 1 }

# List — metadata only, at most 100 records
curl https://agents.clusterbase.dev/v1/environments/env_9a8b7c/browser-passwords \
  -H "Authorization: Bearer $CLUSTER_TOKEN"

# Delete — expected_revision is a query parameter
curl -X DELETE "https://agents.clusterbase.dev/v1/environments/env_9a8b7c/browser-passwords/1c9b7b2e-...?expected_revision=1" \
  -H "Authorization: Bearer $CLUSTER_TOKEN"
```

Responses carry only `id`, `origin`, `display_name`, and `revision` — the
username and password are encrypted together and never echoed back, and there
is no endpoint that returns them in plaintext.

Update by sending the full record again with the current `revision` as
`expected_revision`; a `PUT` always replaces the label, username, and password
together. The `origin` is immutable after creation and must be an exact HTTPS
origin (no path, no userinfo). A stale `expected_revision` on either `PUT` or
`DELETE` returns `409` — refetch the list to get the current revision before
retrying. A save that would exceed 100 records also returns `409`. Once deleted, an id is retired and cannot be recreated by a delayed
retry of the original create.

## Lifecycle [#lifecycle]

Archiving an environment blocks further password management but keeps the
encrypted records. Deleting the environment deletes its passwords with it;
deleting or replacing only the backing VM does not.

## Agent sign-in behavior [#agent-sign-in-behavior]

When a task needs a sign-in, Clusterbot submits a saved or already-filled login
form and checks the resulting page to confirm it worked, without asking you to
approve the login. It never reads, reveals, copies, or types credential values.
When no usable saved login exists or a username/password login is rejected,
it sends a secure sign-in request: you enter the credentials in the Web or
Mobile secure form and choose whether to save them, and the browser fills and
submits the login form. It hands control to you when secure sign-in is
unavailable or the form is unsupported, when SSO, a passkey, or 2FA needs your
input or presence, and for CAPTCHAs. Payments
always need separate explicit approval; signing in does not authorize one.