Skip to content

Self-Hosted Quickstart

Scaffold the recommended local stack with no prompts (safe in CI, scripts, and agents, since it never waits for input):

Terminal window
npx seamless-cli init my-app --local --yes --email=you@example.com
cd my-app
docker compose up

--local scaffolds a self-hosted stack, --yes takes the recommended answer for every remaining question, and --email sets the owner address that becomes the first admin when you register with it. The result is a React web app, an Express API, the auth server as a Docker image, and the admin console served by the API at /console. The full flag list is in the CLI Command Reference.

This guide walks through the fastest supported way to run Seamless Auth yourself: scaffold a project with the CLI, start the stack locally, and sign in as the first admin. The steps below use the interactive form so you can see each choice.


What you will need to complete this walkthrough

Section titled “What you will need to complete this walkthrough”
  • Node 22 or newer (the CLI’s supported range is >=22)
  • Docker with Docker Compose, which runs Postgres and every other service for you
  • A terminal
  • A web browser

The Seamless Auth CLI is published as seamless-cli and exposes the seamless binary. It scaffolds a working local project around the auth ecosystem.

Today it is primarily used to:

  • Scaffold the web app and API starter
  • Configure the auth server in Docker or local mode
  • Optionally include the admin dashboard
  • Generate local secrets and service-to-service wiring
  • Validate the generated local stack
  • Make the email you give it the first admin

You can inspect the CLI here:


Before starting, you can inspect available commands:

Terminal window
npx seamless-cli --help

This will show:

  • Every command (init, templates, check, and the instance commands such as users and config)
  • Usage patterns

check is the command for validating a project init generated. verify is a conformance suite for Seamless contributors and needs a clone of the auth server’s source.

Every command also documents itself, for example npx seamless-cli init --help.


Run the CLI:

Terminal window
npx seamless-cli init my-app
cd my-app

Scaffolding always goes through init. A bare project name (npx seamless-cli my-app) is rejected as an unknown command, and running the CLI with no command prints help.


The CLI will guide you through:

  • The web starter
  • The backend framework
  • Whether to include a mobile starter
  • Your email address. It becomes the owner, and registering with it later makes you the first admin
  • How to run the auth server (Docker or local)
  • Where the admin console is hosted (served by your API at /console, a separate container, or not at all)
Seamless CLI init output
Use seamless-cli init to scaffold a full-stack local auth project

After setup, your project will look like:

my-app/
web/
api/
auth/ # only when local auth mode is selected
admin/ # only when admin source mode is selected
docker-compose.yml
seamless.config.json

The exact shape depends on the options you selected, but the CLI always wires the generated pieces together for local development.


The CLI generates a Docker-based development environment.

Start services:

Terminal window
docker compose up

This will:

  • Start Postgres
  • Start the Seamless Auth server
  • Start a template web application
  • Start a template API server
  • Start the admin dashboard if you included it
  • Use the generated local config and service tokens

Open:

http://localhost:5173

You should see the starter UI with:

  • Login / signup flow
  • Passwordless authentication
  • Session management
Seamless Auth starter UI
Seamless Auth starter UI

If http://localhost:5173 shows a different app, another dev server (often Vite, whose default port is also 5173) holds the port on [::1], and your browser reaches it before the stack. Stop that server, or find it with:

Terminal window
lsof -nP -iTCP:5173 -sTCP:LISTEN

npx seamless-cli check, run in the project, reports a port another program holds.

If the API container exits with an error such as does not provide an export named 'requirePermission', Docker reused images built for an older project in a folder with the same name. Rebuild them:

Terminal window
docker compose up --build

There is no separate admin command. init wrote the email you gave it to the auth server as OWNER_EMAIL, and the auth server grants admin:write to the account created with that address. The starter lists it among your roles as admin:write, not admin.

  1. In the web app at http://localhost:5173, register with the email you gave init.

  2. When asked for a code, get it from the project directory. The local stack sends no email:

    Terminal window
    npx seamless-cli owner-code

    It prints a code for the owner address init recorded.

  3. Enter the code, and enroll a passkey when prompted.

You are now signed in as an admin. Open the admin console at http://localhost:3000/console (or http://localhost:5174 if you chose a separate dashboard container).


You now have a local stack with:

  • A full-stack application
  • A running auth server
  • Connected frontend and backend services
  • Passwordless authentication enabled
  • An admin account for the email you gave init
  • A CLI that can also check the generated stack (npx seamless-cli check)

What You Just Built

  • Web app - API - Auth server - Optional admin dashboard - Local Docker-based infrastructure

Continue to Create Your First User for what happens during sign-in, or Create Your First Admin for how the owner grant works.

Before real users depend on it, read Go Passwordless Without Locking Anyone Out: set up recovery codes and a break-glass admin, and dry-run sign-in policy changes before you publish them.