---
title: Browser Logins (log in once, every agent reuses it)
---

# Browser Logins (log in once, every agent reuses it)

## What it is

**Browser Logins** lets you open a browser, log into **any site(s) you want**, and close it — Omniscio
captures that login automatically (naming it after the site), and from then on every agent you run
can use it — many at the same time — until the site signs you out. It's local-only: no passwords are
stored, and nothing leaves your computer.

It's available to **everyone** — there's nothing to turn on. Reach it two ways (same panel either
way): **Settings → Browser Logins**, or the **Agent Tools → Browser Logins** row in the sidebar
(nested alongside API Keys — both are credential surfaces agents reuse). The browser-automation
tool it uses (`agent-browser`) is installed for you automatically during first-run setup.

This is a **separate, opt-in surface** — it does NOT change how Claude Code sessions, the active
account, or any provider you've connected behave. It's purely a saved browser session your
agents can drive.

### Key facts

- **No passwords stored.** Omniscio saves the _browser session_ (cookies/profile) you create by
  logging in by hand — never your password. Everything stays on your computer.
- **Local-only + revocable.** Remove a login and its master profile + every clone are deleted
  from disk; agents can no longer use it. (Removal is permanent — there's no undo.)
- **On for everyone.** No toggle to flip — the feature is available to all users, and nothing is
  shared or happens until you deliberately add a login. The browser-automation tool it needs is
  installed automatically during first-run setup (best-effort; add it later from Settings →
  Connected Tools if that ever fails).
- **Desktop-only capture.** The saved login works wherever your agents run; _adding_ one needs a
  desktop Chrome window.
- **Imports your old logins (copy, never move).** If you set logins up in Omniscio's earlier
  agent-browser tool, one **Import** click adopts them into Browser Logins; the original store is
  never written, moved, or deleted, so the old tool keeps working too.
- **Not the same as the AI-Drivable Browser's autofill vault.** That's a separate, unrelated
  feature — an encrypted password manager for **your own** tabs inside the (also in-development)
  AI-drivable Browser panel, with zero agent or CLI access. This page's Browser Logins is the
  one agents actually use. See [ai-browser.md](ai-browser.md#autofill-vault-saved-logins-for-your-own-tabs)
  for the comparison table.

## Where to find it

There are two doors to the same panel: the Browser Logins section inside Settings, and the Browser
Logins row in the sidebar under Agent Tools, where it sits next to the key vault because both are
credentials your agents reuse. On a phone only the Settings door is useful, since capturing a
login needs a desktop browser window.

### What you see on the screen

Open it from **Settings → Browser Logins** or the **Agent Tools → Browser Logins** sidebar row.
The panel (identical on both) has:

1. **No setup toggle** — Browser Logins is on for everyone, so there's no "enable" switch; the
   panel below is the feature (nothing is shared until you add a login).
2. **Saved logins** — each saved login shows its name, an Enabled/Disabled pill, the site, and
   when it was added / last used, with a per-row **rename** (the pencil), an **enable/disable**
   toggle, and a **Remove** button. Empty until you add one.
3. **Add a login** — one click opens a real Chrome window at a blank page; you go to **any
   site(s) you want**, log in by hand, then close the window and Omniscio saves the session, **naming it
   automatically after the site** you logged into (rename it later from the list if you like).
   There's no form to fill in. The dialog streams live status
   ("Opening browser… → Waiting for you to log in… → Saved!") plus a Cancel that also closes the
   window. Desktop-only — capture needs a real browser window, so on a phone the section is
   read-only (list / usage / remove stay usable; Add is disabled).
   - **Passkeys do not work in that window — use a password.** Chrome switches WebAuthn off
     whenever a browser is being driven by an automation/debugger connection, which is exactly how
     this capture works; a passkey attempt is refused instantly and no Windows Hello / Touch ID
     prompt appears. The dialog says so, because the browser still *advertises* passkey support and
     sites will happily offer an option that can never complete. This is a deliberate Chrome
     protection against credential theft and is **not** something to work around. Passwords, 2FA
     codes, and email magic links all work normally.
   - **A login you finished is never thrown away.** Closing the window is detected within a few
     seconds and saves immediately; and if a capture runs past its ten-minute ceiling (a slow 2FA,
     a password reset), the finished login is still kept rather than discarded. Nothing is saved
     if you press Cancel, if no session cookies were created, or if the window only ever showed a
     sign-in screen.
4. **Import existing logins** — if you already set up logins with Omniscio's older agent-browser
   tool, a card appears naming them (e.g. "google, porkbun") with an **Import** button. One
   click copies them into Browser Logins so your agents can use them here. Your originals stay
   exactly where they are (untouched), importing twice does nothing, and it works on a phone too
   — it's just a file copy, so it needs no browser window and shows even if the capture tool
   isn't installed. The card only appears when there's something to import.
5. **Usage log** — a read-only record of which agent (or the CLI) used which login, and when.

If the underlying tooling isn't ready (Omniscio's agent-browser helper or a real Google Chrome is
missing) a panel explains what to install and disables **Add**.

## How it behaves

### How agents use a saved login

An Omniscio-spawned agent runs the bundled thin-client:

```bash
amc-browser use gmail
```

That clones the saved "gmail" login for the agent's own session and returns a drivable browser —
no setup, no per-use approval. Agents are told automatically which logins exist (the saved-login
names are injected into the agent's awareness at spawn). Each agent drives its **own clone**, so
many can use the same login concurrently without colliding; the clone is cleaned up when the
session ends.

Each clone runs **headless** — no window opens, on your screen or off it. That is the default and
there is no in-app control to reveal one. The trade-off is real and worth knowing: a headless clone
can get **stuck on "prove you're not a robot" gates like Cloudflare**, so if an agent stalls on a
site that challenges it, that is the likely cause rather than a bug.

A developer who needs to watch a clone work (or to clear a challenge that genuinely needs a real
window) opts in per-run with the environment variable **`AMC_BROWSER_LOGINS_HEADED=1`**. Two things
stay headless regardless: an e2e/sandbox instance (`AMC_INSTANCE_ID`), and any run with the
`AMC_BROWSER_LOGINS_FORCE_HEADLESS` kill switch set. Be aware that the headed window **is a real
window on your screen**, sitting over whatever you were doing. It cannot be hidden or parked
off-screen: the underlying `agent-browser` CLI treats a comma as an argument separator, so Chrome's
`--window-position=x,y` arrives mangled and is ignored — headed and invisible are mutually
exclusive, which is exactly why headless is the default. Only turn it on for the run that needs it.

### Using a saved login in the in-app browser (agent tab + your own tabs)

> **Note (2026-08-02):** the in-app **AI-drivable Browser** referenced below is **RETIRED** — Omniscio
> consolidated on **[My Real Chrome](real-chrome-bridge.md)** (drive your own signed-in Chrome via the
> companion extension). This section is kept for reference; for a real, logged-in browser prefer My Real
> Chrome. Saved **Browser Logins** themselves (above) are unaffected.

A saved login isn't only for external CLI agents — it can also be pointed at Omniscio's
**in-app** [AI-drivable Browser](ai-browser.md) (itself in-development, behind the same kind of Lab
flag). Two ways to use it there:

- **Give the in-app agent a saved login.** The browser pane's isolated **agent tab** normally has
  its own empty profile. You can seed a saved login into it so the in-app agent acts as that login —
  **one saved login at a time** (choosing another re-seeds the same agent tab, replacing the first).
  It's still isolated: the agent tab is only ever seeded from a login **you** captured, never from
  your own everyday browsing, so this doesn't let the agent act as *you*.
- **Open a login in your own tab.** You can also open a saved login in one of *your own* tabs — it
  gets its own private space (a per-login partition) so it never mixes with your normal in-app
  browsing and is never something the agent can reach. This is now reachable **directly from the
  Browser pane** (no Settings trip): with Browser Logins on, its toolbar shows an **"Open signed in"**
  control (key icon) that opens the pane **already signed in** on the login's partition — one login
  opens on click, multiple show a picker, and a "Signed in as <name> · Exit" indicator returns you to
  normal browsing. It needs only the `browser-logins` flag, so it works in the plain single-page pane
  too (see [Embedded Browser → Google sign-in caveat](embedded-browser.md#google-sign-in-caveat)).

**Honest caveat — this is best-effort and cookies-only.** The in-app browser is a different engine
than the real-Chrome clone external agents use, so a saved login is applied there by copying its
**cookies** (the full session, http-only auth cookies included) into the in-app browser — it does
**not** carry `localStorage`/`IndexedDB`, and it can't refresh a token that rotates. So:

- Ordinary cookie-session sites work in-app.
- Some single-page apps and **certain Google surfaces** keep their sign-in in `localStorage` rather
  than cookies, so they may still show **logged-out** in-app, and a rotating token can go stale —
  for those you may need to **re-log-in by hand** in the in-app browser.
- If nothing could be copied, the tab just opens logged-out — it never errors.
- **External CLI agents are unaffected** — they keep using the full-profile clone (the complete,
  most-reliable path), which carries everything cookies alone can't.

### Login freshness (does the saved login still work?)

A saved login lasts until the site signs you out. Three signals keep a stale one from silently failing an agent:

- **Verify on save** — capture won't save a login that never got past a sign-in screen (you closed the window without finishing). Conservative: it never discards a login you actually completed — any doubt, it saves. So a bare sign-in page can't be frozen and handed to agents.
- **Expiry check on use** — `amc-browser use <name>` returns a `loginState` (`ok` | `expired` | `unknown`) with the session. `expired` = the saved cookies no longer authenticate (the clone opened on a sign-in page); the agent still gets the browser but now _knows_ it's logged out instead of failing silently. Best-effort; never blocks the use.
- **Keep-warm (proactive)** — a background job (~6-hourly) probes each stale login and, when one is signed out, raises a single inbox alert ("re-capture X" → Settings → Browser Logins) so you fix it _before_ an agent hits it. It probes via a throwaway clone — the saved master profile is never opened or modified.

Invariants for all three: [browser-logins-reliability-contract.md](../../.claude/memory/contracts/browser-logins-reliability-contract.md).

## For agents

### Under the hood (for agents)

- Renderer: [BrowserLoginsSettings.tsx](../../src/renderer/src/features/settings/sections/browser-logins/BrowserLoginsSettings.tsx)
  — the saved-logins list / add-capture / usage-log UI; writes route through `useIpcAction`
  (humanized errors, never raw). This ONE component renders on both surfaces.
- In-pane "Open signed in" control (Pathway B, classic Browser pane):
  [BrowserSignInControl.tsx](../../src/renderer/src/features/browser/BrowserSignInControl.tsx) +
  [use-browser-logins-list.ts](../../src/renderer/src/features/browser/use-browser-logins-list.ts),
  wired through `BrowserToolbar.tsx` / `BrowserView.tsx`. Reuses `BROWSER_LOGIN_USE_IN_APP` (target
  `human`) to open a HUMAN tab on `humanLoginPartition(id)` (`persist:browser-login-<id>`); gated on
  `browser-logins` visibility; never the agent partition (contract `in-app-cookie-seed-adapter`).
- Sidebar surface: the `browser-logins` integration manifest
  ([integrations/browser-logins.ts](../../src/shared/integrations/browser-logins.ts),
  `parentGroupId: 'agent-tools'`) + the `BROWSER_LOGINS_PROJECT_ID` (`__browser_logins__`)
  virtual project. The panel
  [BrowserLoginsPanel.tsx](../../src/renderer/src/features/browser-logins/BrowserLoginsPanel.tsx)
  wraps `<BrowserLoginsSettings/>` full-pane (`panelOwnsLayout`, NON-spawnable), feeding it
  `settings` + `updateSetting` from the settings store. The sidebar row is gated by the
  `browser-logins` feature via `UNRELEASED_PROJECT_GATES` in
  [project-visibility.ts](../../src/renderer/src/stores/project-visibility.ts) — now that the
  feature is `shipped`, the gate resolves visible for everyone, so the row appears by default.
- Engine (Main): [browser-logins](../../src/main/services/browser-logins/) — capture, per-agent
  clone, leak-proof sweep, plus login-state detection
  ([login-state.ts](../../src/main/services/browser-logins/login-state.ts)) driving verify-on-save,
  expiry-on-use, and a 6-hourly keep-warm probe; namespaced `amc-bl-*` so it never collides with a hand-run broker;
  plus the one-time read-only importer
  ([browser-import.ts](../../src/main/services/browser-logins/browser-import.ts)) that adopts
  legacy `~/.agent-browser-logins` logins (copy-not-move, transactional).
- Agent CLI: `GET /browser-logins/list` + `POST /browser-logins/use` on the CLI control server,
  driven by the bundled [amc-browser.mjs](../../scripts/amc-browser.mjs) thin-client. Behavior is
  locked by [browser-logins-contract.md](../../.claude/memory/contracts/browser-logins-contract.md); the
  freshness signals (verify-on-save / expiry-on-use / keep-warm) by
  [browser-logins-reliability-contract.md](../../.claude/memory/contracts/browser-logins-reliability-contract.md).

## Related

Driving a browser you are already signed into yourself, through your own Chrome rather than a
clone, is a different mechanism described on the [My Real Chrome](real-chrome-bridge.md) page. The
in-app browser these logins can also be pointed at, including its own separate autofill vault for
your own tabs, is on the [AI-drivable browser](ai-browser.md) page.