Quickstart

This guide gets you up and running with Ory Kratos in under 5 minutes using Docker Compose. You’ll run a complete authentication system with email/password login, registration, and a test UI.

Prerequisites

Before you begin, ensure you have:

Docker installed
Docker Compose installed
Basic familiarity with command-line tools

Quick start with Docker Compose

Clone the Ory Kratos repository

Download the quickstart configuration files:

git clone https://github.com/ory/kratos.git
cd kratos

Alternatively, download just the quickstart files without cloning the entire repository.

Start Kratos and dependencies

Run the quickstart with Docker Compose:

docker-compose -f quickstart.yml up

This starts the following services:

Kratos (ports 4433 and 4434) - The identity server
Kratos UI (port 4455) - Example self-service UI
MailSlurper (ports 4436 and 4437) - Test email server
Database migration - Automatic schema setup

Use -d flag to run in detached mode: docker-compose -f quickstart.yml up -d

Verify services are running

Check that all services started successfully:

docker-compose -f quickstart.yml ps

You should see all containers in “Up” state.Test the health endpoint:

curl http://127.0.0.1:4433/health/ready

Expected response:

{"status":"ok"}

Access the UI

Open your browser and navigate to:

http://127.0.0.1:4455/

You’ll see the Kratos self-service UI. Click “Sign Up” to create your first account.

Create your first identity

Using the UI
Using the API
Using the CLI

Register via browser

Navigate to registration

Go to http://127.0.0.1:4455/registration

Fill in the registration form

Enter your details:

Email address (e.g., user@example.com)
Password (must meet strength requirements)
First and last name (optional)

Complete registration

Click “Sign Up” to create your account. You’ll be automatically logged in.

Check verification email

Open MailSlurper at http://127.0.0.1:4436 to see the verification email.

Create identity via Admin API

Create an identity using the Admin API:

curl -X POST http://127.0.0.1:4434/admin/identities \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "default",
    "traits": {
      "email": "user@example.com",
      "name": {
        "first": "John",
        "last": "Doe"
      }
    },
    "credentials": {
      "password": {
        "config": {
          "password": "MySecurePassword123!"
        }
      }
    }
  }'

Response:

{
  "id": "e01b5f2e-8c5a-4b9a-9c1a-8d7e6f5a4b3c",
  "schema_id": "default",
  "state": "active",
  "traits": {
    "email": "user@example.com",
    "name": {
      "first": "John",
      "last": "Doe"
    }
  },
  "created_at": "2026-03-03T12:00:00Z",
  "updated_at": "2026-03-03T12:00:00Z"
}

Import identity with Kratos CLI

First, create an identity file:

cat > identity.json <<EOF
{
  "schema_id": "default",
  "traits": {
    "email": "user@example.com",
    "name": {
      "first": "John",
      "last": "Doe"
    }
  }
}
EOF

Import the identity:

docker-compose -f quickstart.yml exec kratos \
  kratos import identities identity.json \
  --endpoint http://127.0.0.1:4434

Test authentication

Initiate login flow

Navigate to the login page:

http://127.0.0.1:4455/login

Or initialize a login flow via API:

curl -X GET http://127.0.0.1:4433/self-service/login/browser

Submit credentials

Enter the email and password for the identity you created.For API-based login, first get the flow ID, then submit:

# Get the login flow
FLOW_ID=$(curl -s http://127.0.0.1:4433/self-service/login/api | jq -r '.id')

# Submit credentials
curl -X POST http://127.0.0.1:4433/self-service/login?flow=$FLOW_ID \
  -H "Content-Type: application/json" \
  -d '{
    "method": "password",
    "password_identifier": "user@example.com",
    "password": "MySecurePassword123!"
  }'

Verify session

Check your active session:

curl -X GET http://127.0.0.1:4433/sessions/whoami \
  -H "Cookie: ory_kratos_session=YOUR_SESSION_TOKEN"

Response includes identity details and authentication methods used:

{
  "id": "session-id",
  "active": true,
  "identity": {
    "id": "e01b5f2e-8c5a-4b9a-9c1a-8d7e6f5a4b3c",
    "traits": {
      "email": "user@example.com"
    }
  },
  "authenticated_at": "2026-03-03T12:00:00Z"
}

Understanding the quickstart configuration

The quickstart.yml file configures a complete Kratos environment:

version: '3.7'
services:
  kratos-migrate:
    image: oryd/kratos:v25.4.0
    environment:
      - DSN=sqlite:///var/lib/sqlite/db.sqlite?_fk=true&mode=rwc
    volumes:
      - type: volume
        source: kratos-sqlite
        target: /var/lib/sqlite
      - type: bind
        source: ./contrib/quickstart/kratos/email-password
        target: /etc/config/kratos
    command: -c /etc/config/kratos/kratos.yml migrate sql -e --yes
    restart: on-failure

  kratos:
    depends_on:
      - kratos-migrate
    image: oryd/kratos:v25.4.0
    ports:
      - '4433:4433' # public
      - '4434:4434' # admin
    environment:
      - DSN=sqlite:///var/lib/sqlite/db.sqlite?_fk=true
      - LOG_LEVEL=trace
    command: serve -c /etc/config/kratos/kratos.yml --dev --watch-courier
    volumes:
      - type: volume
        source: kratos-sqlite
        target: /var/lib/sqlite
      - type: bind
        source: ./contrib/quickstart/kratos/email-password
        target: /etc/config/kratos

  mailslurper:
    image: oryd/mailslurper:latest-smtps
    ports:
      - '4436:4436'
      - '4437:4437'

Other quickstart variants

Ory Kratos includes several quickstart configurations for different use cases:

PostgreSQL

docker-compose \
  -f quickstart.yml \
  -f quickstart-postgres.yml \
  up

Production-ready PostgreSQL database

MySQL

docker-compose \
  -f quickstart.yml \
  -f quickstart-mysql.yml \
  up

MySQL 8.0 database backend

CockroachDB

docker-compose \
  -f quickstart.yml \
  -f quickstart-crdb.yml \
  up

Distributed SQL database

WebAuthn

docker-compose \
  -f quickstart.yml \
  -f quickstart-webauthn.yml \
  up

Passkey and biometric authentication

Exploring the Admin API

The Admin API runs on port 4434 and provides full identity management capabilities:

List all identities

curl http://127.0.0.1:4434/admin/identities

Get a specific identity

curl http://127.0.0.1:4434/admin/identities/{identity-id}

Update an identity

curl -X PUT http://127.0.0.1:4434/admin/identities/{identity-id} \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "default",
    "traits": {
      "email": "updated@example.com",
      "name": {
        "first": "Jane",
        "last": "Smith"
      }
    }
  }'

Delete an identity

curl -X DELETE http://127.0.0.1:4434/admin/identities/{identity-id}

Cleanup

To stop all services and remove containers:

docker-compose -f quickstart.yml down

To also remove volumes (this deletes all data):

docker-compose -f quickstart.yml down -v

Next steps

Installation

Install Kratos for production use

Configuration

Customize authentication methods and flows

Identity schemas

Define custom identity attributes

Self-service flows

Understand login, registration, and recovery

This quickstart uses --dev mode which disables critical security features. Never use development mode in production.

Get Started

Concepts

Self-Service Flows

Authentication Methods

Identity Management

Session Management

Deployment

Security

CLI Reference

Quickstart

Quickstart

Prerequisites

Quick start with Docker Compose

Create your first identity

Register via browser

Create identity via Admin API

Import identity with Kratos CLI

Test authentication

Understanding the quickstart configuration

Other quickstart variants

PostgreSQL

MySQL

CockroachDB

WebAuthn

Exploring the Admin API

List all identities

Get a specific identity

Update an identity

Delete an identity

Cleanup

Next steps

Installation

Configuration

Identity schemas

Self-service flows

Build docs developers (and LLMs) love

Get Started

Concepts

Self-Service Flows

Authentication Methods

Identity Management

Session Management

Deployment

Security

CLI Reference

​Quickstart

​Prerequisites

​Quick start with Docker Compose

​Create your first identity

​Register via browser

​Create identity via Admin API

​Import identity with Kratos CLI

​Test authentication

​Understanding the quickstart configuration

​Other quickstart variants

PostgreSQL

MySQL

CockroachDB

WebAuthn

​Exploring the Admin API

​List all identities

​Get a specific identity

​Update an identity

​Delete an identity

​Cleanup

​Next steps

Installation

Configuration

Identity schemas

Self-service flows

Build docs developers (and LLMs) love

Quickstart

Prerequisites

Quick start with Docker Compose

Create your first identity

Register via browser

Create identity via Admin API

Import identity with Kratos CLI

Test authentication

Understanding the quickstart configuration

Other quickstart variants

Exploring the Admin API

List all identities

Get a specific identity

Update an identity

Delete an identity

Cleanup

Next steps