Amazon Cognito User Pools emulator for local development.

Warning: cognitox is designed for local development and testing only. It is not suitable for production use. CORS is fully open (Allow-Origin: *) and there is no authentication on the admin endpoints.

# Pull pre-built image from GitHub Container Registry
docker pull ghcr.io/unvalley/cognitox:latest
docker run -p 9229:9229 ghcr.io/unvalley/cognitox:latest

docker build -t cognitox .
docker run -p 9229:9229 cognitox

cargo install cognitox
cognitox

The admin console and Preact UI are embedded into the binary, so cargo install gives you a fully self-contained emulator — no extra assets to ship.

Point the SDK endpoint to cognitox:

// JavaScript / TypeScript
import { CognitoIdentityProviderClient } from "@aws-sdk/client-cognito-identity-provider";

const client = new CognitoIdentityProviderClient({
  region: "local",
  endpoint: "http://localhost:9229",
  credentials: { accessKeyId: "local", secretAccessKey: "local" },
});

# Python (boto3)
import boto3

client = boto3.client(
    "cognito-idp",
    region_name="local",
    endpoint_url="http://localhost:9229",
    aws_access_key_id="local",
    aws_secret_access_key="local",
)

cognitox includes a built-in Hosted UI for login and signup flows.

// example
http://localhost:9229/login?response_type=code&client_id=<client-id>&redirect_uri=http://localhost:3000/callback&scope=openid

A management UI for browsing user pools, users, clients, and groups:

http://localhost:9229/admin/

By default, all data is in-memory and lost on restart. To persist state:

COGNITOX_DATA_FILE=./cognitox-data.json cargo run

The emulator auto-saves every 500ms when changes are detected, and flushes on graceful shutdown (Ctrl+C).

cognitox has all 119 API operations but some have partial functionality or known limitations (see below). See COVERAGE.md for the full list with links to each handler. If you find any missing or incorrectly implemented operations, please open an issue.

See spec/README.md.

• SRP authentication (USER_SRP_AUTH) -- partially implemented
• Lambda triggers -- not supported (no pre/post auth hooks)
• Email/SMS delivery -- confirmation codes are returned in API responses but not sent
• Password policy per pool -- only global min/max length is enforced
• MFA enforcement -- MFA operations are implemented but not enforced during auth
• Advanced security features -- risk configuration is stored but not evaluated

MIT