First boot

Pitot validates configuration before opening data files or listeners. Invalid settings stop startup with an error naming the setting. See configuration for precedence, secret files and validation.

Local sign-in requires PITOT_AUTH_CODE_SECRET with at least 32 characters. SMTP and an AI provider are optional; each validates its required settings when enabled. OIDC requires an HTTPS issuer and public URL, a client ID and a client secret. The generated settings reference lists the available authentication settings.

Claiming the first administrator

When the control database holds no users, Pitot prints a one-time setup URL to standard error:

============================================================
 PITOT SETUP

 Open:  http://127.0.0.1:7520/login?setup_token=…
 Valid: one-time use, expires in 1 hour
 Note:  this URL disappears after the first admin is created
 Warn:  it contains an administrator credential — this output may
        persist in container logs, log aggregators, and scrollback
============================================================

Under Docker, read it back with:

docker logs pitot 2>&1 | grep -A8 "PITOT SETUP"

Open the URL, create the administrator, and save the ingest token shown after setup. The raw token is displayed once; Pitot stores only its hash and cannot show it again. If PITOT_INGEST_TOKEN already set the token, setup shows no token and leaves that one in place.

An administrator can create more named tokens on the ingest token page, which is /settings/ingest on your Pitot instance, or under Connect telemetry in the account menu. To rotate a token without downtime, create a replacement, move the Collector to it, then revoke the old one. See ingest tokens.

The setup form sends email, display_name, and setup_token to POST /api/auth/setup. The first administrator starts with status active.

The setup URL is an administrator credential. Restrict access to process logs until it is consumed or expires. Treat a leaked setup URL as a compromised installation and rebuild with a fresh data directory before repeating setup.

Signing in afterwards

Local mode has no passwords. Once SMTP is configured, active users receive short-lived codes by email. Without SMTP, run pitot login-link <email> with the server’s environment and data directory to mint a 15-minute, single-use link for an existing active user. For Docker, use:

docker exec pitot pitot login-link [email protected]

OIDC deployments use the provider’s flow instead.

Next

Send your first telemetry, then investigate it with Pitot’s agent or an MCP client.