First-time setup

On an empty state database, Envoy redirects every browser to the setup screen. The first account created there becomes the initial superadmin.

Before opening the UI

Confirm that:

• the control plane is reachable at its final browser-facing URL;
• HTTPS and secure cookies are configured together in production;
• the encryption key and executor key are present;
• the state database or persistent state directory is durable;
• at least one executor is available if executor.type is http.

Create the first account

1. Open the Envoy URL.
2. Enter the administrator username.
3. Enter and confirm a password of at least eight characters.
4. Select Create Account.

If auth.totp_required is disabled, Envoy signs in immediately. TOTP is required by default when the setting is omitted.

Enroll in TOTP

When TOTP is required:

1. Scan the QR code with an authenticator application.
2. Store the displayed manual secret through your organization's approved process.
3. Enter the six-digit code.
4. Select Complete Setup.

The QR code is rendered locally in the browser. The TOTP URI is not sent to an external QR-code service.

If enrollment is interrupted, the next password login continues or allows the enrollment to be restarted. An unverified pending session cannot access the authenticated API.

Verify server health

Open Settings and check the server status. In a split deployment, also open Executors and confirm:

• the expected executor URL appears;
• its status is healthy;
• its capacity matches the configured concurrency limit;
• its heartbeat continues to update.

Local execution mode does not show remote executors because tasks run as subprocesses on the control-plane host.

Create the first connectors

Go to Connectors, then create the source and destination connections needed by your first task. Test each connection before saving or running work.

For Docker file connectors, use paths inside the container:

CSV or YAML: /app/data
SQLite:      /app/dbs/quickstart.db

See Connectors for secret fields, file uploads, connected accounts, and connection tests.

Invite other users

Open Users to create admin or viewer accounts. Envoy returns a single-use invite link. The recipient sets a password and, when required, enrolls in TOTP.

Invite links shown by the current UI expire after 48 hours. Regenerate an unused link from the user's row actions if needed.

See Users, settings, and authentication and RBAC, secrets, and hardening before assigning roles.

Next step

Follow the UI quickstart to run the bundled CSV-to-SQLite example, or CLI quickstart to execute the same task from a terminal.