First-Run Setup

A fresh self-hosted Atomic instance starts unclaimed when it has no active API tokens. The first user claims it by creating the initial token.

Setup UI

  1. Start the server and web UI.
  2. Open the web URL, such as http://localhost:8080.
  3. Follow the setup wizard.
  4. Save the displayed API token. It will not be shown again.
  5. Configure an AI provider.

The setup wizard connects the browser to the server with the new token and stores the connection in browser local storage.

Public Setup API

Check whether setup is required:

curl http://localhost:8080/api/setup/status

Response:

{

"needs_setup": true

}

Claim the instance:

curl -X POST http://localhost:8080/api/setup/claim \

-H "Content-Type: application/json" \

-d '{"name": "admin"}'

Response:

{

"id": "token-id",

"name": "admin",

"token": "raw-token-shown-once",

"prefix": "token-pref",

"created_at": "timestamp"

}

After claim, create additional tokens from Settings or POST /api/auth/tokens.

CLI Alternative

If you are running server-only and do not have the web setup UI available:

atomic-server --data-dir ./data token create --name admin

Use the same --data-dir, ATOMIC_STORAGE, and ATOMIC_DATABASE_URL configuration that your server uses.

Desktop App Difference

The desktop app does not require claiming a public instance. It creates a local token named desktop for the sidecar server and passes that token to the frontend through Tauri IPC.