Setup Wizard

When Operator starts and no .tickets/ directory exists, the setup wizard guides you through first-time initialization. This reference documents each step of the wizard.

Steps Overview

Step	Name	Description
1	Welcome	Name the configuration and review detected tools and projects
2	Operator Premium	Install or review the Premium licence for this configuration
3	Execution Mode	Run agents on this machine, or on remote targets
4	Kanban Info	Connect an external kanban provider, or skip and connect one later
5	Model Server	Declare which model providers this workspace uses
6	Git Provider	Connect a git provider so agents can branch, push and open PRs
7	Collection Source	Choose which issue type collection to use
8	Hosted Collections	Browse and select hosted collections (only shown if Browse chosen)
9	Task Field Config	Configure optional fields for TASK issue type
10	Session Wrapper Choice	Select which session wrapper to use for launching coding agents
11	Execution Target	Choose whether agents run locally or in Coder workspaces
12	Worktree Preference	Choose whether to use git worktrees for ticket isolation
13	Web UI Password	Optionally set the admin password for the web dashboard
14	Tmux Onboarding	Help and documentation about tmux session management (shown if tmux selected)
15	VS Code Setup	VS Code extension setup and verification (shown if VS Code selected)
16	Cmux Setup	cmux session wrapper setup (shown if cmux selected)
17	Zellij Setup	Zellij session wrapper setup (shown if Zellij selected)
18	Acceptance Criteria	Review and configure acceptance criteria for ticket completion
19	Startup Tickets	Optionally create tickets to bootstrap your projects
20	Confirm	Review settings and confirm initialization

Step Details

1. Welcome

Name the configuration and review detected tools and projects

Choose a configuration name containing only lowercase letters, digits, hyphens, and underscores. The name identifies this configuration in the web UI, TUI, CLI, and MCP clients; its UUID remains stable when renamed.

The welcome screen also displays:

Detected LLM tools (Claude, Gemini, Codex, etc.) with version and model count
Discovered projects organized by which LLM tool marker files they contain
The path where the tickets directory will be created

This gives you an overview of your development environment before proceeding.

Navigation: Enter to continue, Esc to cancel

2. Operator Premium

Install or review the Premium licence for this configuration

Multiple local agents and local containers are free. Premium adds remote execution: SSH hosts and Coder workspaces.

A licence is verified offline - Operator never contacts a licensing service. It is bound to this configuration’s identifier, shown on this screen, and survives renaming the configuration.

Paste a licence key to install one, or continue without: every local workflow stays available.

Navigation: Enter to install, Tab to skip, Esc to go back

3. Execution Mode

Run agents on this machine, or on remote targets

Both modes support multiple agents running at once.

This machine: agents and local containers run beside Operator.
Remote targets: agents run on SSH hosts or Coder workspaces and report back to this Operator server. Requires Premium.

Choosing remote leads to target registration; choosing this machine skips it.

Navigation: ↑/↓ to select, Enter to continue, Esc to go back

4. Kanban Info

Connect an external kanban provider, or skip and connect one later

Operator is the board. Tickets worked by agents move through the columns. It is always on and needs no setup or credentials.

External providers are optional sync sources: their issues are pulled in as tickets on the Operator board, and transitions are pushed back. Supported: Jira, Linear, GitHub Projects, OpenSpec.

Credentials already exported (e.g. OPERATOR_JIRA_API_KEY) are listed as detected providers.

Connect a kanban provider opens the same onboarding dialog the dashboard uses: pick a provider, enter its credentials, validate them against the live API, and choose a project. The provider section is written to config.toml and the token is exported into this session, with a shell snippet to make it permanent.

Skip for now moves on with just the Operator board; press K from the dashboard at any time.

Navigation: ↑/↓ to select, Enter to confirm, Esc to go back

5. Model Server

Declare which model providers this workspace uses

Model providers are where inference happens - distinct from the agent CLI that calls them.

Each provider is probed live: a row reads N models when Operator can reach it, key missing when its API key env var is unset, or unreachable with the reason.

Space declares a provider, writing a [[model_servers]] entry. Operator stores only the name of the environment variable holding the key, never the key itself - export it in your shell to make it permanent.

Providers needing a custom base URL (OpenAI-compatible, LM Studio) are listed but not selectable here; add them to config.toml directly.

This step is optional - Operator ships working defaults for the first-party vendors.

Navigation: ↑/↓ or j/k to navigate, Space to declare, Enter to continue, Esc to go back

6. Git Provider

Connect a git provider so agents can branch, push and open PRs

Operator branches per ticket and opens pull requests on your behalf, which needs a provider and a token.

Each row reports what was found: the provider CLI (gh, glab, tea) not installed, an existing CLI login Operator can adopt with no typing, or a prompt for a personal access token.

Only the name of the environment variable holding the token is written to config.toml. The token itself is exported into this session, and the step prints the shell line to make that permanent - without it the token is gone when Operator exits.

This step is optional; Operator works against a local repository with no provider connected.

Navigation: ↑/↓ or j/k to navigate, Enter to connect, Esc to go back

7. Collection Source

Choose which issue type collection to use

Select a preset collection of issue types:

Simple: Just TASK - minimal setup for general work
Dev Kanban: 3 types (TASK, FEAT, FIX) for development workflows
DevOps Kanban: 5 types (TASK, SPIKE, INV, FEAT, FIX) for full DevOps
Custom Selection: Choose individual issue types

Navigation: ↑/↓ or j/k to navigate, Enter to select, Esc to go back

8. Hosted Collections

Browse and select hosted collections (only shown if Browse chosen)

Pick one or more curated collections published at operator.untra.io.

The list is fetched from the collections manifest; if it cannot be reached, the collections bundled with Operator are offered instead. Each collection brings its own issue types and workflow steps.

Selections are additive - choose as many as apply.

Navigation: ↑/↓ or j/k to navigate, Space to toggle, Enter to continue, Esc to go back

9. Task Field Config

Configure optional fields for TASK issue type

TASK is the foundational issue type. Configure which optional fields to include:

priority: Priority level (P0-critical to P3-low)
points: Story points estimate
user_story: User story or background context

These choices propagate to other issue types. The ‘summary’ field is always required, and ‘id’ is auto-generated.

Navigation: ↑/↓ or j/k to navigate, Space to toggle, Enter to continue, Esc to go back

10. Session Wrapper Choice

Select which session wrapper to use for launching coding agents

Choose how Operator will manage coding agent sessions:

tmux: Terminal multiplexer, recommended for most setups
VS Code: Launch agents as VS Code tasks (requires extension)
cmux: Native macOS terminal for AI agents, organized into windows and workspaces
Zellij: Modern terminal workspace with built-in layouts

Your choice determines which setup steps follow.

Navigation: ↑/↓ or j/k to navigate, Enter to select, Esc to go back

11. Execution Target

Choose whether agents run locally or in Coder workspaces

Local runs agent commands on the same machine as Operator. Coder creates or starts a per-ticket workspace and launches there over SSH.

Coder configuration stores only environment variable names for the deployment URL and session token. Secret values remain in the process environment.

Coder targets disable git worktrees and relay injection, and cannot be combined with Zellij.

Navigation: ↑/↓ to select, Tab to switch fields, Enter to continue, Esc to go back

12. Worktree Preference

Choose whether to use git worktrees for ticket isolation

Configure how Operator manages git branches per ticket:

In-place branches: Each agent works in the main checkout, switching branches
Git worktrees: Each ticket gets its own worktree directory for full isolation

Worktrees allow multiple agents to work on different tickets simultaneously without branch conflicts.

Navigation: ↑/↓ or j/k to navigate, Enter to select, Esc to go back

13. Web UI Password

Optionally set the admin password for the web dashboard

Operator has a single human account, admin.

This terminal and the CLI need no password: a loopback process authenticates with an owner-only token file in the state directory. A browser cannot read that file, so the web dashboard stays locked until an admin password exists.

Leave both fields blank to skip. You can set one later with operator auth bootstrap or from the /setup page.

The password must be at least 12 characters. This step is hidden when an admin account already exists.

Navigation: Tab to switch fields, Enter to continue (blank to skip), Esc to go back

14. Tmux Onboarding

Help and documentation about tmux session management (shown if tmux selected)

Operator launches Coding agents in tmux sessions. Essential commands:

Detach from session: Ctrl+a (quick, no prefix needed!)
Fallback detach: Ctrl+b then d
List sessions: tmux ls
Attach to session: tmux attach -t <name>

Operator session names start with ‘op-‘ for easy identification.