Zitadel — next generation

The next generation of the Zitadel identity platform, built for developers and AI agents alike: registration and login live in your app, under your brand, while Zitadel guards the credentials, sessions, and tokens underneath.

Preview status: This work rebuilds Zitadel's storage core and API surface, so it ships as a preview in its own repository and is intended to merge back into zitadel/zitadel as the foundation of a future major version. APIs, CLI flags, package surfaces, and docs are still in flux. Create-first, claim-later is the product direction, and zitadel claim ships in this repo (ADR 046). The full story is in VISION.md.

Workflow front doors

I am contributing to Zitadel

See CONTRIBUTING.md for contributor setup (including the devcontainer), Moon commands, local checks, integration tests, source builds, and release workflows. Agent-facing workspace rules live in AGENTS.md.

I am adding Zitadel to my app

I want to...	Run
Check local runtime prerequisites	npx @zitadel/cli@alpha doctor
Start local Zitadel	npx @zitadel/cli@alpha start
Add auth to my app	npx @zitadel/cli@alpha setup --server local
Check generated app files	npx @zitadel/cli@alpha doctor
Stop local Zitadel, keeping data	npx @zitadel/cli@alpha stop
Delete local Zitadel data	npx @zitadel/cli@alpha reset --force

The published zitadel runtime commands run the released local runtime through the @zitadel/server npm binary by default and do not require Docker, Go, Moon, or a source checkout. Docker remains available with zitadel start --runtime docker.

I am an agent (or driving one)

The CLI is the agent-facing surface today: every command supports --non-interactive --json and returns a structured envelope. apps/cli/SKILLS.md is the canonical contract for agents integrating Zitadel into an app; AGENTS.md is for agents contributing to this repository. The documentation site publishes LLM-friendly text at /llms.txt, /llms-full.txt, and page-level .md URLs.

Customer quick start

mkdir myapp
cd myapp
npx @zitadel/cli@alpha doctor

Pick a server before running setup — it can't be changed on this app afterward. Use --server local for local dev, or point at a hosted Zitadel Cloud instance if you intend to claim the project later and attach it to your team:

npx @zitadel/cli@alpha start                # local dev only
npx @zitadel/cli@alpha setup --server local  # or --server https://api.zitadel.cloud
npm run dev

Open http://localhost:3000/login and register your first user. setup walks through the scaffold choices (such as which framework and use case) and writes the app into the current directory; pass --skip-install if you want to install dependencies yourself. With --server local, the managed Zitadel runtime stores its metadata and data under .zitadel/local/; stop preserves that data and reset --force deletes it — none of that applies against a hosted server, which has no local runtime to manage.

Claim your project (Zitadel Cloud only)

If you set up against Zitadel Cloud above, attach the project to your team once the app is up:

npx @zitadel/cli@alpha claim

This opens a browser so you can sign in with your own Zitadel account (not one of the app's end users) and attach the project to your team. The link prints before any browser opens, so it works over SSH or headless too (--no-open); nothing about the running project changes. Claiming only works within 14 days of running setup — after that, setup a fresh project instead.

Trying this before deploying to Zitadel Cloud: claiming needs a server with a platform project bootstrapped, which Zitadel Cloud has by default. To exercise the same flow locally today, run the Docker deploy with the platform project enabled and use http://localhost:8080 as the --server above — see docker-compose.md and configuration.md § Platform. This box goes away once claiming against Zitadel Cloud is verified end to end.

Manual Docker quick start

Run the API and embedded UIs with Docker Compose when you want to inspect the operator-style stack directly:

cd docs/operations
cp env.example .env
docker compose up -d

Surface	URL
Management console	http://localhost:8080/ui/console/
Sign-in shell	http://localhost:8080/ui/login/
Health	http://localhost:8080/healthz

Details: docs/quick-start/index.md. To build from source: CONTRIBUTING.md.

Documentation site

The Fumapress/Fumadocs documentation skeleton lives in apps/docs.

moon run docs:dev
moon run docs:build

The docs app bundles the OpenAPI source into a generated reference, exposes static search, and publishes LLM-friendly text at /llms.txt, /llms-full.txt, page-level .md URLs, and /mcp.

Current status

This repository is pre-release. The Go server command serves the OpenAPI surface and embeds the console and login UIs at /ui/console/ and /ui/login/. CI produces installable snapshots for review, not official releases.

For product direction and the four pillars, see VISION.md.

CI

Pull requests are gated by the GitHub Actions context full-pr, shown in the pull request UI as ci / full-pr. On a 16-core runner it runs a Go generated-file drift check, lint, type checks, builds, unit and browser tests, Go tests including Postgres/Spanner/SQLite dialect integration, a non-publishing release snapshot, and fresh-app journeys against the snapshot's npm tarballs. Changesets version PRs run a smaller release validation path instead, and Changesets comments give release-intent feedback without adding a blocking gate. The full step list lives in .github/workflows/ci.yml and CONTRIBUTING.md.

Releases

Moon builds the artifacts (Go binaries, containers, archives) and the draft GitHub Release; Changesets owns versions, npm publishing, and release notes, with the public packages on one fixed alpha train. Build a local snapshot with moon run release:snapshot (more in CONTRIBUTING.md). To cut or recover a release, follow the release runbook; for when to add a changeset, see .changeset/README.md; for the rationale, see ADR 002.