Skip to content

Guide: Sessions / authenticated pages

What is this?

Pass a local session profile (cookies, headers, and optionally Playwright storageState) so Occam can fetch pages behind a login you already completed in a real browser.

Do not assume session_profile behaves the same on every tool. Occam applies three session tiers depending on the call path.

Three session tiers

Tier What is applied Typical tools
1 — Full browser + headers HTTP headers and Playwright storageState (cookies + localStorage) occam_transcode, occam_digest, occam_claim_check, occam_attest, occam_dataset_export, occam_playbook_heal, occam_extract_knowledge, opt-in batch/watch/crosscheck
2 — Headers only (HTTP path) Cookie/header bag for HTTP workers; no storageState occam_probe, occam_map

Headers-only vs storageState: a profile can store auth in two shapes:

  • Header/cookie bag — works on Tier 1–2 for HTTP header injection.
  • storageState file — Playwright cookie jar + localStorage; required for many SPAs and client-side auth walls. Loaded by Tier 1 tools (including heal and extract_knowledge browser fallback). On Tier 2, the file is not read — no error is returned, so check the tier before you debug a failed login.

See also: Sessions overview · Configuration — session profiles

When should I use it?

  • requires_login, captcha_or_challenge (session may help only if you already passed the wall — Occam does not solve CAPTCHAs), or empty/thin anonymous extracts on authenticated content.
  • Prefer backend_policy=browser when the wall is client-side (SPA, JS-gated content).

Minimal flow

  1. Init the sessions directory (once): occam session init or node scripts/occam-session.mjs init.
  2. Create a profile:
  3. Cookies only: occam session import --from cookies.txt --host example.com --id example-com
  4. Full browser state: occam session export-state --url https://example.com/login --id example-com (headed browser; you log in, then Occam saves storageState).
  5. Profiles live under OCCAM_SESSIONS_ROOT (default ~/.occam/sessions/).
  6. Pass session_profile: "<id>" on tools that support it.
{
  "name": "occam_transcode",
  "arguments": {
    "url": "https://example.com/private",
    "session_profile": "example-com",
    "backend_policy": "browser"
  }
}

Secrets on disk

Session profiles are credentials on disk:

Location Contents Risk
OCCAM_SESSIONS_ROOT/<id>.json Profile metadata, header map, storageState path Cookies, auth headers
OCCAM_SESSIONS_ROOT/states/ Playwright storageState JSON Cookies, localStorage tokens
OCCAM_SESSIONS_ROOT/_imports/ Raw import sources only when you opt in Plaintext cookie files

Import default: occam session import does not retain a plaintext copy under _imports/ unless you pass --keep-import. The default is safer; use --keep-import only when you intend to keep the source file.

Protect OCCAM_SESSIONS_ROOT like a password store. Do not commit profiles. Do not put LLM API keys in Occam's environment.

Expected result

Same as a normal transcode when the session is valid and the tool tier matches how your auth is stored.

What can go wrong?

Symptom Likely cause
Still requires_login Expired cookies, wrong profile id, or Tier 2 tool (probe/map) with storageState-only auth
session_profile_not_found Id missing under OCCAM_SESSIONS_ROOT
captcha_or_challenge CAPTCHA or bot wall — Occam does not solve CAPTCHAs; sessions carry your state only
Auth works on transcode but not probe/map Expected — Tier 2 never loads storageState

Next