Skip to main content
The kratos serve command starts the Ory Kratos server, which includes both the public and admin HTTP APIs.

​
Usage

kratos serve [flags]

​
Description

This command starts the Kratos server with both the public-facing API (for identity flows like login, registration, etc.) and the admin API (for identity management). The server reads its configuration from a YAML configuration file. The serve command initializes:
  • Public API - Handles self-service flows (login, registration, settings, recovery, verification)
  • Admin API - Provides identity management endpoints
  • Message courier - Optionally runs as a background task for sending emails

​
Flags

​
Configuration

Path to the configuration file.
kratos serve --config /path/to/config.yml

​
Development flags

​
--dev

Disables critical security features to make development easier.
DO NOT USE IN PRODUCTION!This flag disables security features including CSRF protection and other safeguards. It should only be used in development environments.
kratos serve --dev --config config.yml
When running in dev mode, you’ll see this warning: 
YOU ARE RUNNING Ory KRATOS IN DEV MODE.
SECURITY IS DISABLED.
DON'T DO THIS IN PRODUCTION!

​
Telemetry

​
--sqa-opt-out

Disable anonymized telemetry reports. 
kratos serve --sqa-opt-out --config config.yml
For more information about telemetry, visit the Ory SQA documentation.

​
Courier

​
--watch-courier

Run the message courier as a background task to simplify single-instance setup. 
kratos serve --watch-courier --config config.yml
The courier is responsible for sending emails for account verification, password recovery, and other email-based flows. When this flag is enabled, you don’t need to run a separate kratos courier watch process.
In production deployments with multiple instances, it’s recommended to run the courier as a separate process to avoid duplicate email sends.

​
Examples

​
Basic server start

Start the server with a configuration file: 
kratos serve --config /etc/kratos/config.yml

​
Development mode

Run the server in development mode with the courier enabled: 
kratos serve \
  --dev \
  --config config.yml \
  --watch-courier

​
Production deployment

Run the server in production with telemetry disabled: 
kratos serve \
  --config /etc/kratos/config.yml \
  --sqa-opt-out

​
Docker deployment

docker run -it \
  -v $(pwd)/config.yml:/etc/config.yml \
  -p 4433:4433 \
  -p 4434:4434 \
  oryd/kratos:latest \
  serve --config /etc/config.yml

​
Server endpoints

When the server starts, it exposes two sets of endpoints:

​
Public API (default: port 4433)

The public API is used by your application’s frontend:
  • /self-service/login/* - Login flows
  • /self-service/registration/* - Registration flows
  • /self-service/settings/* - Settings flows
  • /self-service/recovery/* - Account recovery flows
  • /self-service/verification/* - Email verification flows
  • /sessions/whoami - Get current session information
  • /health/alive - Liveness check
  • /health/ready - Readiness check

​
Admin API (default: port 4434)

The admin API is used for identity management:
  • /admin/identities - Identity CRUD operations
  • /admin/recovery/link - Create recovery links
  • /admin/schemas - Identity schemas
  • /health/alive - Liveness check
  • /health/ready - Readiness check
  • /metrics/prometheus - Prometheus metrics

​
Configuration

The serve command requires a configuration file. Here’s a minimal example: 
version: v1.0.0

dsn: memory

serve:
  public:
    base_url: http://localhost:4433/
    cors:
      enabled: true
  admin:
    base_url: http://localhost:4434/

selfservice:
  default_browser_return_url: http://localhost:3000/
  
  flows:
    login:
      ui_url: http://localhost:3000/login
    registration:
      ui_url: http://localhost:3000/registration

identity:
  default_schema_id: default
  schemas:
    - id: default
      url: file:///etc/config/identity.schema.json

​
Health checks

The serve command exposes health check endpoints for monitoring:

​
Liveness probe

curl http://localhost:4433/health/alive
Returns 200 OK if the server is running.

​
Readiness probe

curl http://localhost:4433/health/ready
Returns 200 OK if the server is ready to accept requests (database connection is healthy, migrations are complete, etc.).

​
Graceful shutdown

The server supports graceful shutdown with a default timeout of 120 seconds. When receiving a termination signal (SIGTERM or SIGINT), the server will:
  1. Stop accepting new requests
  2. Wait for active requests to complete (up to 120 seconds)
  3. Close database connections
  4. Exit

​
Troubleshooting

​
Server won’t start

Check that:
  • Configuration file exists and is valid YAML
  • Database connection string is correct (if using a database)
  • Ports 4433 and 4434 are not in use
  • Required environment variables are set

​
Version mismatch warning

If you see: 
Config version is 'v0.13.0' but kratos runs on version 'v1.0.0'
Update your configuration file’s version field to match the Kratos version.

​
Missing version warning

If you see: 
The config has no version specified. Add the version to improve your development experience.
Add a version field to your configuration file: 
version: v1.0.0

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us