GUIDES

Self-hosting runs the studio inside your app so it’s available at a URL you choose (e.g. /api/studio or /admin). Only people who pass your access rules (roles or allowlisted emails) can open it. The studio is served by your framework, so it works in production without a separate process.

Before adding the studio you need:

• 1. A project using Better Auth (with auth exported from e.g. lib/auth.ts or src/auth.ts).
• 2. A database and adapter (Prisma, Drizzle, or SQLite) already configured in that auth.
• 3. Node 18+ and pnpm (or npm/yarn).

Step 1: Install the package

Use a regular dependency (not dev) so the studio is available in production.

Step 2: Generate the config file

From your project root, run the init command. It will create studio.config.ts (or studio.config.js) and, for some frameworks, the route file.

Step 3: Point config to your auth

Open studio.config.ts and set auth to your Better Auth instance (e.g. import { auth } from "./lib/auth").

Step 4: Mount the studio in your app

Depending on your framework, you mount the handler on a path that matches basePath in config (default /api/studio). For exact code per framework, see the Next.js guide below or the Self-hosting page.

If you don’t have a project yet:

Then add Better Auth and your database adapter (see Better Auth docs). You should end up with something like src/lib/auth.ts (or lib/auth.ts) exporting auth and an API route for auth (e.g. app/api/auth/[...all]/route.ts).

Install as a regular dependency so it runs in production:

For local-only use you can use pnpm add -D better-auth-studio and run pnpm better-auth-studio start instead of embedding the route.

Run the init command to generate the config and, for Next.js, the API route file:

It creates studio.config.ts at the project root and app/api/studio/[[...path]]/route.ts. The route file should look like this:

import { betterAuthStudio } from "better-auth-studio/nextjs";
import studioConfig from "@/studio.config";

const handler = betterAuthStudio(studioConfig);

export { handler as GET, handler as POST, handler as PUT, handler as DELETE, handler as PATCH };

If your config lives elsewhere, change the import (e.g. from "@/studio.config" or from "../../studio.config").

Open http://localhost:3000/api/studio (or the basePath you set in studio.config.ts). You’ll be asked to sign in; only users who match your access config can use the studio.

Same flow: install better-auth-studio, run pnpx better-auth-studio init to get studio.config.ts, then mount the framework adapter on the path that matches basePath (e.g. /api/studio).

1. Create or open your project and set up Better Auth (auth instance + database).
2. pnpm add better-auth-studio
3. pnpx better-auth-studio init – creates studio.config.ts. Point it at your auth.
4. Import the adapter (e.g. better-auth-studio/hono, better-auth-studio/express) and mount the handler on basePath.

All customization lives in studio.config.ts: auth, basePath, access, metadata, and optionally tools, events, lastSeenAt, ipAddress. Below is what each does and how to set it.

URL path where the studio is served. Default /api/studio. Your app must serve the handler on this path.

basePath: "/admin"

• roles – Array of Better Auth role names (e.g. ["admin"]).
• allowEmails – Array of emails allowed when not using roles.
• sessionDuration – Studio session length (e.g. seconds).
• secret – Secret for signing the studio session; set in production.

access: {
  roles: ["admin"],
  allowEmails: ["admin@example.com"],
  sessionDuration: 60 * 60 * 24,
  secret: process.env.STUDIO_SECRET,
}

• title, logo, favicon
• theme – "dark" | "light" | "auto"
• colors – primary, secondary, accent
• company – name, website, supportEmail
• features – Toggle users, sessions, organizations, analytics, tools, security
• links – [{ label, url }]

metadata: {
  title: "My Admin",
  logo: "/logo.png",
  theme: "dark",
  colors: { primary: "#0ea5e9" },
  company: { name: "Acme", supportEmail: "support@acme.com" },
  features: { tools: true, analytics: true },
}

Use tools.exclude with ids like test-oauth, health-check, run-migration to hide them from the Tools page.

tools: { exclude: ["test-oauth", "health-check"] }

Optional event ingestion for the Events dashboard: events.enabled, client / clientType (prisma, drizzle, sqlite, etc.), include / exclude event types, liveMarquee.