Skip to content
z4j docs

Create the first admin

On first boot z4j has no users. It prints a setup URL to stderr inside an ASCII banner:

╔══════════════════════════════════════════════════════════════════════╗
║                         z4j first-boot setup                         ║
║                                                                      ║
║ Open this URL in your browser to create the admin:                   ║
║                                                                      ║
║ http://localhost:7700/setup?token=yAXssHbiYxnJfohZeqOejGA8b14C0mKPEm║
║                                                                      ║
║ Token expires at: 2026-04-23T16:52:27+00:00 (UTC)                    ║
║ Single-use. Restart z4j to generate a new one.                 ║
║ For zero-log-exposure setup, use Z4J_BOOTSTRAP_ADMIN_*.              ║
╚══════════════════════════════════════════════════════════════════════╝

The token is a one-shot urlsafe-random string valid for 15 minutes, stored hashed. Visit the URL.

If the token expired or you closed the terminal, mint a fresh one without losing data:

Terminal window
z4j reset-setup

That prints a new banner with a fresh URL. The DB and any existing users are untouched.

Setup form

Section titled “Setup form”

The setup page asks for:

  • Email - becomes the admin username.
  • Password - minimum 8 characters, at least 3 of 4 character classes (lowercase, uppercase, digits, symbols), not in the common-password denylist. See password policy.
  • Organization name - creates the first project.

On submit, z4j:

  1. Creates the user with role owner.
  2. Creates the first project (slug derived from the org name).
  3. Invalidates the setup token (one-shot).
  4. Signs you in and redirects to the dashboard home.

Bootstrap without the setup URL

Section titled “Bootstrap without the setup URL”

For IaC pipelines that cannot read a browser setup URL, set Z4J_BOOTSTRAP_ADMIN_EMAIL + Z4J_BOOTSTRAP_ADMIN_PASSWORD before first boot. z4j provisions the admin automatically and the setup banner is suppressed. See env vars.

Equivalent CLI form (works after first boot too):

Terminal window
z4j createsuperuser --email you@dev.local --display-name "You"
# or non-interactively:
echo 'sup3r-secret!' | z4j createsuperuser --email you@dev.local --display-name "You" --password-stdin

What to do next

Section titled “What to do next”
  1. Mint an agent token - go to /projects/{slug}/agents in the dashboard, click new agent, and copy BOTH the token AND hmac_secret from the dialog before closing. Both are shown ONCE.
  2. Install the agent - see the install guide and pick the framework + engine combo that matches your app.
  3. Wire it up - Django quickstart, Flask, FastAPI, or bare Python.
  4. Invite your team - Settings, Memberships, Invite. Requires an active email notification channel on the project for auto-delivery; otherwise the dashboard surfaces the link for out-of-band sharing. See SMTP presets.

Losing admin access

Section titled “Losing admin access”

If you lose the last admin account, there is no in-app recovery (by design - that would be a back-door). You must:

  1. Connect to the Postgres database directly.
  2. Run UPDATE users SET password_hash = '...' WHERE email = '...' with a valid argon2id hash.
  3. Or set Z4J_BOOTSTRAP_ADMIN_* and restart; z4j will provision a fresh admin.

Production deployments should always have at least two admins.