Skip to main content
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. 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.
Classic repositories configure this in Niteshift settings instead: see Preview authentication (classic).

​
Recording a session

The recording flow uses a real task to capture real cookies. There’s no separate “recording mode”.
1

Declare the recorded type

Set auth.type: recorded on the service in services.yaml, then open the Recorded sessions section of Settings → Repositories → [repository].
2

Click Record session

Niteshift starts a short-lived task that boots an environment and opens the browser at your app.
3

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.
4

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.
Every future task on that repository, started by you, boots with the recorded session pre-loaded.
Recordings are per-user. Each developer records once per repository they work on.

​
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.