Authentication Methods

Thread Vault CLI supports two authentication paths. Both write credentials to the same local cache/session.json file using atomic file I/O. Sessions are validated against the Instagram inbox API on every startup.

The recommended method. Press A on the Auth Screen (or click Launch Browser). Thread Vault opens a headed Chromium window sized 480×720px. Log in to Instagram normally — including 2FA if enabled.

🔄

Automatic Cookie Capture

A background thread polls the browser context for sessionid and csrftoken cookies every 800ms. As soon as both are detected, the browser closes automatically.

🧵

Non-blocking Thread

Playwright's sync API runs in a dedicated background thread. The Textual event loop continues running — the TUI remains responsive during the entire login process.

⏱

5-Minute Timeout

You have 300 seconds (5 minutes) to complete the Instagram login flow before the browser session times out. This is generous enough for 2FA and CAPTCHA scenarios.

💾

Atomic Write

Captured cookies are written to cache/session.json atomically via a temp-file swap — preventing corruption if the process is interrupted mid-write.

WHAT GETS CAPTURED
# cache/session.json schema
            {
            "session_id": "<your_session_id_cookie>",
            "csrf_token": "<csrftoken_cookie>",
            "user_pk": "<extracted_from_session_id>",
            "username": "<populated_after_inbox_validation>"
            }
          

⚠

Prerequisite: Browser Login requires Playwright + Chromium installed. Run uv run playwright install --with-deps chromium once before using this method. If the binary is missing, Thread Vault will show an error with the exact command to run.

Method B — Session ID Manual Entry

Press B (or click Paste Session ID). A text input appears — paste your raw sessionid cookie value and press Enter. No browser required.

How to find your session ID

Open Instagram in your browser

Navigate to instagram.com and ensure you're logged in.

Open DevTools

Press F12 (Windows/Linux) or Cmd+Option+I (macOS) to open browser DevTools.

Navigate to Application → Cookies

Click the Application tab → expand Cookies → click https://www.instagram.com.

Copy the sessionid value

Find the row with Name: sessionid. Copy the Value column — it looks like 12345678%3AaBcDeFgHiJkLmNoP%3A12.

⚠

Security: Your sessionid cookie grants full access to your Instagram account. Never share it. Thread Vault stores it only in cache/session.json on your local filesystem and never transmits it to any server other than www.instagram.com.

Session Validation

Every startup, Thread Vault validates the cached session by probing the Instagram inbox API (/api/v1/direct_v2/inbox/?limit=1). This is more reliable than hitting the profile endpoint because it confirms the session can actually fetch DM data.

✅

Validation Success

The startup screen shows "Continue as @username" with a Logout option. The username and user PK are extracted from the inbox API's viewer field and stored in the session model.

❌

Validation Failure

If the probe returns {"status": "fail"} or raises an exception, the cached session file is deleted and the Auth Screen is shown. No stale credentials persist.

Logout

From the startup screen (if a valid session is found), click Logout or press the associated key. This calls clear_session() which deletes cache/session.json. The full Session Data Isolation purge also runs — clearing all scraped messages, cursor state, and thread cache from disk.

🔒

What's stored: cache/session.json contains your session ID, CSRF token, user PK, and username. cache/inbox_cache.json stores your thread directory listing for fast re-loads. Both files are deleted on logout. No passwords are ever stored or requested by Thread Vault.