> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niteshift.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser session

> Configure how the agent and your previews authenticate into your application.

The agent's browser and your preview links share a single authentication session per task. Configure
how that session is seeded at **Settings → Repositories → \[repository] → Preview Authentication**.

Four strategies:

* **No auth**: previews show the unauthenticated view. No credentials are stored or injected.
* **Use static cookies across all tasks**: record a session once (or paste cookies in by hand) and
  Niteshift injects them into every task's browser and preview links. Best for hosted auth providers
  (AuthKit, Clerk, Okta) and persistent backing services (Neon, Supabase).
* **Per-task login**: your setup script writes cookies to `/tmp/agent-browser-state.json`, and
  Niteshift syncs that file to the agent's browser on launch and to preview links so you see the
  same authenticated session the agent does. Best for per-task seeded users or short-lived sessions.
  Use **Edit with agent** to have the setup agent draft the seeding code for you.
* **Manual login (username & password)**: add [custom instructions](https://niteshift.dev/settings)
  with test credentials (e.g. `user@example.com` / `test123`) and the login flow. The agent drives
  the login itself each task, and you can also log in manually on previews.

## Recording a session

The recording flow uses a real task to capture real cookies. There's no separate "recording mode".

<Steps>
  <Step title="Pick the recorded-cookies strategy">
    Go to **Settings → Repositories → \[repository] → Preview Authentication**, select **Use static
    cookies across all tasks**, and click **Save**.
  </Step>

  <Step title="Click Record session">
    Niteshift starts a short-lived task that boots an environment and opens the browser at your app.
  </Step>

  <Step title="Log in via Control Browser">
    The task pauses and surfaces a **Control Browser** prompt. Take over the browser tab and log in
    the way a user would: SSO, 2FA, anything. The agent waits.
  </Step>

  <Step title="Save">
    Once you're logged in and on a page that proves it, click **Save**. Niteshift exports cookies
    and localStorage, encrypts them, and stores them scoped to that repository and to your user.
  </Step>
</Steps>

Every future task on that repository, started by you, boots with the recorded session pre-loaded.

<Note>Recordings are per-user. Each developer records once per repository they work on.</Note>

## Debugging login issues

Most preview-auth failures share a root cause: when your app needs to authenticate, it sends the
user to a hosted sign-in page (AuthKit, Clerk, Okta) that refuses to render inside an iframe. The
preview blanks out or breaks.

For **Use static cookies across all tasks** and **Per-task login**, Niteshift sidesteps this by
issuing a bootstrap request to the preview domain to plant cookies, then loading your application.
Because the session is already in place, your app doesn't redirect to a hosted sign-in and the
iframe-bust never triggers.

Without authentication configured (**No auth**), apps that redirect to a login on mount or require a
"Sign in with X" click will fail to load in the preview.

If previews still fail to authenticate, prompt the setup agent via **Edit with agent** to configure
authentication for your previews. It can debug cookie shape, redirect behavior, or bootstrap config.

Still stuck? Reach out at [support@niteshift.dev](mailto:support@niteshift.dev).