Record a session

The record provider is the shortcut for any auth system: you sign in once in the managed browser, valetkey captures the resulting session, and your agent uses it. No mint function, no provider API, no knowledge of how your auth works.

This is the fastest way to get valetkey working, and often the only practical option for auth you do not control, such as a third-party identity provider in your dev environment.

Set it up

npm install -D @valetkey/record

import { record } from "@valetkey/record";
import { defineConfig } from "valetkey";

export default defineConfig({
  app: {
    name: "myapp",
    origins: ["http://localhost:3000"],
  },
  provider: record({
    signInUrl: "http://localhost:3000/login",
    waitForCookie: "session",
  }),
  personas: {
    admin: { seed: { email: "admin@myapp.test" } },
  },
});

Both options are optional. Without signInUrl valetkey opens the first configured origin; without waitForCookie it considers you signed in as soon as any cookie appears for your origins, which is usually right but can trigger early on apps that set a CSRF cookie before login.

Use it

valetkey login admin --browser

A Chrome window opens at your sign-in page and valetkey tells you to sign in. Type the credentials yourself, in a real browser, with your password manager. Nothing about that goes near the agent. Once your session cookie exists, valetkey captures the cookies and localStorage, saves the session, and injects it.

From then on the agent works signed in, and valetkey login admin refreshes without asking you again until the session actually stops working.

Personas with recorded sessions

Recording is per persona, so sign in once per account:

valetkey login admin --browser
valetkey login free-user --browser

Each capture is stored separately, and switching between them afterwards needs no interaction at all.

Options

Option	Default	Effect
signInUrl	first configured origin	Where the browser opens
waitForCookie	any cookie appearing	Which cookie means “signed in”
timeoutMinutes	5	How long valetkey waits for you

Trade-offs

Recording is manual, once per persona per expiry, so it does not suit CI. It also cannot create users; the account has to exist already. When you want fully unattended sessions and seeded users, write a provider or wait for the first-party plugin for your auth library.

What it does give you is a working setup in about two minutes, and a session your agent can hold without your password ever being typed anywhere near it.