> ## 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 authentication

> 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, so an app
with a login opens already signed in instead of on a login wall.

The service that serves the login declares an `auth` block in
[`services.yaml`](/environment-configuration/services#preview-authentication). Three types, by where
the session comes from:

* **`magic-dev-login-url`**: the app serves a development-only login route that authenticates a
  seeded user, sets the session cookie, and redirects. The best fit when such a route exists:
  Niteshift stores no auth state, and every visit gets a fresh session.
* **`cookie-file`**: a command signs in without user interaction (a seeded user, a CLI, an API) and
  writes browser state that Niteshift injects into the agent's browser and syncs to preview viewers.
* **`recorded`**: Niteshift replays a session you record once by hand, from the **Recorded
  sessions** section of **Settings → Repositories → \[repository]**.

Prefer `magic-dev-login-url` or `cookie-file`: they mint sessions automatically, without your
involvement. Use `recorded` only when nothing can sign in on its own (SSO, 2FA, CAPTCHA); recorded
sessions expire and pull you back in to re-record.

The agent picks and wires a type during setup. To change it, ask the agent in any task: agents know
how to edit `.niteshift/` configuration and open a PR with the change.

<Note>
  [Classic repositories](/environment-configuration/setup-script) configure this in Niteshift
  settings instead: see [Preview authentication
  (classic)](/environment-configuration/classic-preview-auth).
</Note>

## Recording a session

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

<Steps>
  <Step title="Declare the recorded type">
    Set `auth.type: recorded` on the service in `services.yaml`, then open the **Recorded sessions**
    section of **Settings → Repositories → \[repository]**.
  </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 the stored-state types (`cookie-file` and `recorded`), 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, 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, ask the agent in a task 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).