Configuration

valetkey loads valetkey.config.ts from your project root. The config is TypeScript, validated on every load, and safe to commit; secrets are referenced by vault key, never written into it.

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

export default defineConfig({
  app: {
    name: "myapp",
    origins: ["http://localhost:3000", "http://localhost:5173"],
  },
  provider: custom({
    mint: async (ctx, persona) => {
      // ...
    },
  }),
  personas: {
    admin: { seed: { email: "admin@myapp.test", role: "admin" } },
  },
  session: {
    ttlMinutes: 60,
  },
  allowRemoteDevOrigins: ["https://staging.myapp.dev"],
});

app

name identifies the project in artifact paths (~/.valetkey/sessions/<name>/) and the audit log. Lowercase letters, digits, and hyphens.

origins lists where sessions may be injected. Every origin must be a dev host: localhost, 127.0.0.1, [::1], or a hostname ending in .localhost, .test, or .local. Anything else fails validation unless it appears in allowRemoteDevOrigins. Cookies minted for hosts outside this list are rejected.

provider

A provider plugin instance. Today that means custom() from @valetkey/custom; Better Auth, Auth.js, and Supabase plugins are on the roadmap. Writing your own is covered in the provider guide.

personas

A map of persona name to { seed }. Names must start with a lowercase letter or digit and may contain letters, digits, hyphens, and underscores; they become artifact filenames. The seed object is opaque to valetkey and passed straight to your provider, so its shape is whatever your mint and seed functions expect.

session

ttlMinutes caps how long a minted session stays usable. Defaults to 60. Providers can return shorter expiries; longer ones are clamped down to this value. Expired artifacts are pruned automatically and refuse to export.

allowRemoteDevOrigins

An escape hatch for remote dev or staging environments. Origins listed here pass the dev-origin check, with one extra rule: they must be https. Do not put production here. The guardrail exists so that a config typo cannot point an agent’s session at real users.

Secret references

Anywhere a plugin needs a secret, reference it by vault key and read it with ctx.secrets.get("KEY") at mint time. Config validation rejects string values that look like live credentials, so a real key pasted into the config fails before it can be committed.