First-run setup

The first time you open a fresh orboto instance you land in the setup wizard. It only appears while the instance is uninitialized, and it offers three starting points.

The setup token

Two of the three paths below (restore, and import from another instance) ask for a setup token - a one-time secret that proves you're the operator of this specific machine, not a random visitor who reached your fresh instance before you did. You don't need it for a brand-new fresh workspace, only for restore and import.

Where to find it:

• If you set the SETUP_TOKEN environment variable yourself, that's the token - it doesn't change between restarts.
• Otherwise, orboto generates one automatically and prints it once to the container's boot log, in a boxed banner. Read it with docker compose logs api (or your platform's log viewer) right after first boot. It regenerates on every process restart if you never set SETUP_TOKEN, so if you missed it, restart the container and read the log again before you start the wizard.

The token is never returned by any API response - it only ever reaches you through the log. It stops being needed the moment setup completes.

Option 1: Fresh workspace

Two steps, then you're in.

Step 1 - workspace basics.

• Workspace name - shown in the browser tab and in outgoing email templates. Required.
• Workspace language - the initial UI language for the admin account you're about to create, and the language used for default email templates. Individual users can still pick their own display language later, once they're in - this only sets the starting point.
• Workspace timezone - pre-filled from your browser, but editable. This is not a display preference: it's the single timezone your scheduled jobs (backups, reminders, cron-based alerts) are anchored to. Get this right if your server runs in a different zone than the browser you're setting it up from - individual users set their own display timezone separately, later, in their profile.

Step 2 - the administrator account. Your name, email, and password. This becomes the first user in the workspace, with full administrator access.

Submit, and you're signed in immediately. The admin configuration wizard then walks you through the common areas (email, AI, integrations) inside the app at your own pace - none of it blocks you from using orboto right away.

Option 2: Restore from a backup

Choose this to move an existing workspace onto this instance from a backup archive you already have - see Backups for how archives are produced.

1. Enter the setup token for this instance (see above).
2. Select or drag in the archive file (.zip).
3. Select Start restore.

The instance restores every user, project, and file from the archive, then shows a summary: how many rows across how many tables, and how many storage objects (attachments, avatars, and so on) came along. If anything in the archive couldn't be applied cleanly, it's listed as a warning below the summary rather than silently dropped - read those before you continue. Select Go to sign in and use the credentials from the backup - not new ones, the account you restored already exists with its original password.

Option 3: Import from another orboto instance

Choose this to pull a complete, running workspace directly from another live orboto instance - including its attachments - without producing an intermediate archive file yourself. Useful for moving from orboto Cloud to self-hosted, or between two self-hosted instances, without a manual export/download/upload round-trip.

You need two tokens from two different places:

1. On the source instance (the one you're moving from), sign in as an admin and go to Admin → Backup → Migration export access, and create an export token there (it looks like orbexp_…). This is a separate credential from your account password, scoped only to this migration.
2. On this instance (the fresh one you're setting up), gather the setup token as described above.

Then, in the wizard:

• Source instance URL - the full address of the instance you're importing from (for example https://old.example.com).
• Export token - the orbexp_… token from step 1.
• Setup token - this instance's own setup token from step 2.

Select Start import. This can take a while for a large workspace - it pulls the full database export and then transfers every storage object (attachments, avatars) one by one. If some files fail to transfer (a network blip, a temporary permission issue), the result screen tells you how many and offers Retry missing files, which only re-attempts what's still missing rather than starting over. Once it's done, sign in with the credentials from the old instance - everything came along, including passwords.

Notes

• The wizard is rate-limited and disabled the moment setup completes - it can never be re-run against a live instance, by any of the three paths.
• If the instance shows the normal sign-in screen instead of the wizard, it is already initialized.

Troubleshooting

The wizard rejects my setup token as "invalid or missing". Cause: you typed it wrong, it regenerated on a restart because SETUP_TOKEN was never pinned in your environment, or setup already completed on this instance (the token stops being checked afterwards). Fix: re-read the current token from the boot log (docker compose logs api), or set SETUP_TOKEN explicitly in your environment so it stops changing between restarts.

I reach the wizard again after setup already completed. Cause: this shouldn't happen on a genuinely initialized instance - you are more likely looking at a different instance (a fresh container, or a database that was reset) than the one you set up before. Fix: confirm you're pointed at the right hostname and the right database before restoring or importing anything, so you don't overwrite an existing workspace.

The restore step rejects my backup archive. Cause: the archive is corrupted, from an incompatible version, or the upload was interrupted. Fix: re-download the archive from its original source and try again; see Backups for how archives are produced.

The remote import fails immediately with a connection error. Cause: the source instance URL is unreachable from this server (typo, firewall, or the source instance is actually down), or the export token was already used up or revoked on the source side. Fix: confirm you can reach the source URL from this host, and generate a fresh export token from the source instance's Admin → Backup → Migration export access if you're unsure the old one is still valid.

I can't reach the wizard at all - it goes straight to a sign-in screen. Cause: the instance is already initialized (setup_completed is set). Fix: sign in normally, or restore/import into a fresh database if you intended to start over.