ah desktop login-session

Open an interactive login session for an agent-owned browser profile on Linux.

ah desktop login-session [--profile <NAME>] [--service <chatgpt|claude|gemini|grok>] [--novnc <HOST:PORT>] [--vnc <HOST:PORT>]

This command reuses the managed Chromium profile stored under the selected Agent Browser Profile, opens the right login window for the target service, waits until authentication is detected, and then exits.

It is the Linux M4 login-acquisition command for browser-backed services. Use it when Agent Harbor needs to surface an interactive sign-in flow instead of assuming the profile is already authenticated. On Linux it is also the surface used automatically when ah ask --allow-login, ah research --allow-login, or ah agent ask-expert triggers managed reauthentication for a browser-backed service. You can enable the same behavior by default with ask.allow-login = true or research.allow-login = true in config.

This command is still Linux-only for interactive login. macOS M8 now adds browser survey plus best-effort session import to the broader managed login-acquisition workflow, but the macOS interactive-login surface remains pending until M9. On non-Linux platforms, invoking ah desktop login-session still returns an unsupported-platform error today.

Prerequisites

• The target profile must already exist. Create it first with ah browser-profiles create <NAME> if needed.
• For --service gemini, Agent Harbor launches a real Chromium-family browser and expects one to be installed locally. The current Linux M4 browser survey looks for Google Chrome, Chromium, Microsoft Edge, or Brave.
• In remote-view mode, keep --novnc and --vnc bound to loopback IP literals only (127.0.0.1, ::1, or [::1]). Hostname aliases such as localhost are rejected. The WebUI reaches noVNC through Agent Harbor’s same-origin proxy rather than by exposing those listeners directly.

Linux behavior

Browser selection is provider-driven in the current Linux M4 implementation:

• gemini launches a real Chromium-family browser with --password-store=basic so Google-backed OAuth can complete in a non-Electron browser while still writing cookies into the managed profile.
• chatgpt, claude, and grok keep using the Electron automation host for the interactive login window.

Surface selection is automatic:

• Local desktop: used only when Agent Harbor is running locally, a display server is available ($WAYLAND_DISPLAY or $DISPLAY), and the CLI is attached to an interactive TTY.
• Remote or headless: if the invocation is REST-backed or otherwise remote-managed (AH_REMOTE_SERVER, AH_REST_BASE_URL, or AH_REMOTE_COMMAND_EXEC_SOCKET set), if no display is available, or if stdin/stdout is not an interactive terminal, Agent Harbor launches the existing nested-compositor plus wayvnc plus noVNC path and the user completes login through the WebUI /remote-view page.

Browser-session import is not performed by ah desktop login-session itself. In the broader managed login-acquisition workflow, Agent Harbor now tries a best-effort import first: on Linux it can migrate valid unexpired sessions from surveyed Chromium-family or Firefox profiles into the managed profile; on macOS M8 it does the same for surveyed Chromium-family and Firefox profiles while detecting Safari and failing closed when Safari’s cookie store is blocked by Full Disk Access. If the source store is unreadable, permission-gated, or lacks a valid provider session, the workflow falls back to interactive login where that platform supports it.

That macOS M8 import support belongs to the managed flow used by ah ask and ah agent ask-expert. The older ah browser-profiles discover and ah browser-profiles import-cookies commands still use their legacy manual implementation and do not expose Safari’s Full Disk Access status.

Common failure cases:

• Missing profile: the command exits and tells you to create the named Agent Browser Profile first.
• Missing Chromium-family browser for gemini: the command exits before starting login and asks you to install Chrome/Chromium.
• Non-loopback --novnc or --vnc in remote-view mode: the command rejects the bind address for safety.
• localhost used for --novnc or --vnc: the command rejects hostname aliases; use a loopback IP literal instead.
• Login window exits before authentication is detected: the command fails instead of assuming the partial session is usable.

Options

Set AH_LOGIN_TIMEOUT_SECS to an integer from 0 to 3600 to enforce a timeout. 0 or an unset variable means no timeout. By default the session remains open until login is detected or the user aborts with Ctrl-C.

For remote-view mode, --novnc and --vnc must remain loopback-only IP-literal binds; localhost is not accepted.

Examples

Open a local desktop login window for the default profile:

ah desktop login-session --service chatgpt

Launch the real-browser Gemini login path in a named profile:

ah desktop login-session --profile work --service gemini

Bind a remote-view login session to 15 minutes:

AH_LOGIN_TIMEOUT_SECS=900 ah desktop login-session --service gemini