First-Login Setup Wizard

The first-login setup wizard guides new Breeze administrators through essential platform configuration immediately after their initial sign-in. It covers organization setup and device enrollment in a two-step workflow. Once finished, you are taken to the main dashboard and the wizard does not appear again.

---

When the Wizard Appears

The setup wizard appears automatically the first time the default [email protected] account signs in, before the password has been changed and before setup has been completed or skipped. Users created through invitations or the admin panel will never see the wizard.

Tip

If you have already changed your password or completed the wizard once, it will not appear again. To re-trigger it, a database administrator would need to reset the the setup status and password-changed flag on the admin account.

---

Setup Steps

The wizard presents two sequential steps. Each step can be saved or skipped individually.

1. Organization — Create your organization and first site. This sets up the multi-tenant hierarchy (organization and site) that structures your Breeze deployment. Enter your organization name and create your first site (e.g., “Main Office”).

2. Enroll Device — Install the Breeze agent on your first endpoint. The wizard displays enrollment instructions and an enrollment key you can copy. Follow the on-screen instructions to install the agent and verify connectivity.

After completing or skipping both steps, click Go to Dashboard to finish setup and open the main dashboard.

---

Skipping and Resuming

Skipping Individual Steps

Every step has a Skip button that advances to the next step without making any changes. You can always configure these settings later from the dashboard.

Skipping the Entire Wizard

A Skip Setup link appears below the step card on the first step. Clicking it marks setup as complete and takes you directly to the dashboard. The wizard will not appear again.

Resuming After Interruption

If you close your browser or navigate away before finishing, the wizard remembers which step you were on. When you sign in again, it picks up where you left off.

Note

If you sign out before completing the wizard, you will be redirected back to it on your next sign-in as long as setup is still pending.

---

Troubleshooting

The wizard does not appear after first login. The wizard only activates for the seeded [email protected] account before setup is completed and before the password has been changed. If you have already done either, the wizard will not appear. Verify the admin account has not already completed setup by checking with your database administrator.

The wizard keeps appearing after completion. The completion step may have failed to save. Check the API logs for errors on the setup-complete endpoint. Verify that the database is healthy and the API container logs show no errors.

The page shows a loading spinner indefinitely. The wizard checks your authentication status on load. If the API server is unreachable or CORS is misconfigured, this check will hang. Verify that the API server is running and that CORS allows requests from your frontend domain. Check the browser developer console for network errors.

Technical details

The wizard is rendered at the /setup route as a React component. It checks the requiresSetup flag from GET /users/me to determine whether to display. Completion calls POST /system/setup-complete, which sets the setupCompletedAt timestamp on the user record. Progress is persisted to localStorage under the key breeze-setup-step.