Markdown

Authentication

Three distinct identity flows live in Pi Dash. They all terminate at the Django authentication/ module, but they have very different user experiences and security models.

FlowWho uses itWhere it lives
Instance admin (“god mode”)The person who first stood up the self-hosted instanceapps/admin UI + pi_dash.authentication
User login (password, magic link, OIDC)Day-to-day product usersapps/web + apps/space + pi_dash.authentication
Runner enrollment (device-code + legacy token)The Rust pidash daemonrunner/src/cli/auth + pi_dash.runner.views.enrollment

1. Instance admin (one-time bootstrap)#

The very first thing you do on a fresh self-hosted instance:

http://<your-instance>/god-mode/   ← register the instance admin

This is served by apps/admin/ (port 3001 in dev). Once registered, the admin’s credentials are also valid user credentials on the main app — you log into apps/web with the same identity.

There is no “create admin” CLI command — it’s deliberately a one-shot web flow tied to “the first request to god-mode wins”.

2. User login (web + space)#

Lives in pi_dash/authentication/ (mounted at /auth/):

authentication/
├── views/         ← sign-in, sign-up, password reset, OIDC callbacks
├── serializers/
├── permissions/
├── middleware/
└── urls/

Mechanisms supported (configurable per instance):

  • Email + password (always available)
  • Magic-link / email OTP
  • OIDC / SSO — when configured. Cloud Pi Dash uses the home-page OIDC as the plan source-of-truth: the JWT plan claim is cached on Account and gates Cloud-specific features. There are no plan webhooks — plan updates flow through subsequent OIDC logins. Upgrade UI in the app deep-links back to the home-page user center.

The space app (public/guest views) reuses the same auth module but can serve content without a session.

3. Runner enrollment#

The runner (pidash CLI) needs to authenticate to the cloud without a human at the keyboard for every request. There are two paths:

pidash auth login --url https://your-pidash-instance.com

--url is only needed for a self-hosted instance. Omit it and the CLI reuses this host’s configured [daemon].cloud_url, falling back to the hosted cloud at https://pidash.airepublic.com — so the release installer never has to ask.

  1. CLI requests a device code from the cloud (/api/v1/runner/enroll/...).
  2. CLI shows the user a short code + URL to open in a browser.
  3. User approves in the browser (signed in via flow #2 above).
  4. CLI polls until the code is approved → cloud mints a CLI token.
  5. CLI persists token at ~/.config/pidash/config.toml (0600).
  6. CLI prompts to add a runner inline if none exists on this host.

This is the same UX as gh auth login or stripe login. Bare pidash (no subcommand) drops into this flow when no config exists — useful after MSI install on Windows.

B. Headless login#

For headless hosts where opening a browser automatically is awkward:

pidash auth login --no-browser --url https://pidash.example.com
pidash runner add --project <PROJECT_ID>

The CLI prints the verification URL and user code; approve it from any browser signed in to Pi Dash.

Runner credential model#

After login, the dev machine holds one shared MachineToken. The CLI and every runner on that local machine use the same token; the runner identity is carried separately by URL runner_id or X-Runner-Id.

TokenLifetimeUse
MachineToken (mt_...)Long-livedIdentifies the authenticated dev machine + user + workspace. Stored once in [cli].token at login.
Runner idStableIdentifies the specific runner under that dev machine. Sent in runner URLs or X-Runner-Id, not secret.
Enrollment/refresh tokenLegacyKept only for already-minted pidash connect compatibility paths. New pidash runner add does not use it.

Cloud-side, MachineToken lifecycle is stored in runner.MachineToken; legacy refresh/access helpers remain in pi_dash/runner/services/tokens.py for compatibility.

pidash auth logout revokes the dev-machine token cloud-side. pidash runner remove removes one runner row/local instance without rotating the shared machine token.

On-disk security#

  • Config + credential files: 0600 on Unix.
  • IPC socket between daemon and TUI: 0600.
  • On Windows: files under the user profile, IPC over a local named pipe with appropriate ACLs.

Search Docs and Blog