Auth Setup for Local Agent Testing

Auth is the gate for all automated testing. Complete Step 0.0 first so SERVER_URL and ports are resolved, then verify auth before writing any test step.

Initialize helpers first:

SCRIPT="./.agents/skills/agent-testing/scripts/setup-auth.sh"
TEST_ENV="./.agents/skills/agent-testing/scripts/test-env.sh"
eval "$($TEST_ENV --exports)"

Quick reference after initialization:

Use localhost for Web auth; better-auth cookies are stored for localhost, not 127.0.0.1.

Per-surface overview

CLI — Seeded API key

For the self-contained no-root-.env dev environment, seed the baseline user and API key once:

./.agents/skills/agent-testing/scripts/init-dev-env.sh seed-user
source .records/env/agent-testing-cli.env
./.agents/skills/agent-testing/scripts/setup-auth.sh cli-seed

The seed step writes LOBE_API_KEY for humans and maps it to the CLI's current auth variable, LOBEHUB_CLI_API_KEY. It also sets LOBEHUB_SERVER so CLI commands hit the local server without needing a stored device-code token.

Use this for automated CLI verification:

cd apps/cli
source ../../.records/env/agent-testing-cli.env
bun src/index.ts <command>

CLI — Device Code Flow fallback

Use device-code login only when testing against a non-seeded environment. Credentials are isolated from the user's real CLI config via LOBEHUB_CLI_HOME=.lobehub-dev, which the current CLI stores under $HOME/.lobehub-dev.

cd apps/cli && LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts login --server http://localhost:3010

• The --server flag is required — an env var does NOT work and login will hit the wrong server without it.
• Check state without logging in: setup-auth.sh status (verifies LOBEHUB_CLI_API_KEY when present, otherwise checks the stored server URL).
• UNAUTHORIZED on API calls means the token expired — re-run login.

Web — seeded better-auth login

The Web test surface is agent-browser --session lobehub-dev. The user's ordinary Chrome is only a cookie source; Chrome screenshots, Chrome Network records, and Chrome logged-in state do not prove the agent-browser test session is authenticated.

For the seeded local dev environment, use the automatic path:

./.agents/skills/agent-testing/scripts/init-dev-env.sh seed-user
./.agents/skills/agent-testing/scripts/setup-auth.sh web-seed

web-seed posts the seeded email/password to /api/auth/sign-in/email, stores the returned cookie jar under ~/.lobehub-agent-testing/, converts it to Playwright storageState, loads it into the agent-browser session, and verifies the session does not land on /signin.

Web — manual cookie injection fallback

agent-browser --headed on macOS often creates the Chromium window off-screen — the user can't see or interact with it, so manual login inside the agent-browser session fails. Instead, copy the better-auth session cookie out of the user's own logged-in Chrome and inject it as a Playwright-style state file.

Do not use this on production URLs — only local dev. Treat the cookie as a secret: don't paste it into shared logs, PRs, or commit it anywhere.

Web — decision flow

1. $SCRIPT status --surface web — green? Start testing. Do not ask for a Cookie header.
2. Not green and using the seeded local env → $SCRIPT web-seed.
3. Still not green or not using the seed env → $SCRIPT open-chrome opens Chrome at SERVER_URL with DevTools.
4. User copies the Cookie: header from Network tab → any same-origin request → Request Headers → right-click Cookie: → Copy value. Must be from Network, NOT document.cookie (HttpOnly cookies are invisible to document.cookie).
5. pbpaste | $SCRIPT web — filters to better-auth cookies (session_token, session_data, state), builds Playwright storageState, loads it into the agent-browser session (lobehub-dev), opens SERVER_URL, and asserts the URL is not /signin.

Using the authenticated session

agent-browser --session lobehub-dev open "$SERVER_URL/"
agent-browser --session lobehub-dev snapshot -i | head -20

Notes

• storageState doesn't enforce the HttpOnly flag on load — the script stores cookies with httpOnly: false, which is fine for local dev and sidesteps a CDP-context quirk where HttpOnly cookies sometimes fail to attach.
• The state file is kept at ~/.lobehub-agent-testing/web-state.json so setup-auth.sh status can report web-auth readiness across sessions.

Common failure modes

Electron

The desktop app keeps its own persistent login state in its user-data directory — log in once manually inside the app and it survives restarts of electron-dev.sh. No injection needed. The standard check (do NOT hand-roll a store eval) once Electron is up with CDP:

./.agents/skills/agent-testing/scripts/app-probe.sh auth
# → {"ok":true,"isSignedIn":true,"userId":"user_xxx"}

setup-auth.sh status runs this probe automatically when CDP 9222 is reachable.

Scope

These recipes only cover local dev authentication. They do not:

• Work for production — production cookies are Secure; HttpOnly; Domain=.lobehub.com and must be delivered over HTTPS.
• Replace real OAuth flows — tests that must exercise the login UI itself need a real Chromium with --remote-debugging-port or a bot account.
• Flow cookies back to the user's Chrome — injection is one-way.