feat: open WebUI after fresh desktop install

README.md

@@ -125,7 +125,7 @@ Windows PowerShell:
 irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex
 ```
 
-The default command installs or upgrades `nanobot-ai` from PyPI, then starts `nanobot onboard --wizard`. It avoids system-wide pip installs by using an active virtual environment, `uv`, `pipx`, or a managed venv under `~/.nanobot/venv`. When Quick Start finishes, run `nanobot webui`. The installer also prints the exact command it used to run nanobot; reuse that full command below if `nanobot` is not on `PATH`.
+The default command installs or upgrades `nanobot-ai` from PyPI. On a fresh local desktop, it then starts `nanobot webui` so you can configure the first provider and model in **Settings → Models**. SSH, headless, existing-config, and older-release paths keep the terminal setup wizard. The installer avoids system-wide pip installs by using an active virtual environment, `uv`, `pipx`, or a managed venv under `~/.nanobot/venv`. It also prints the exact command it used to run nanobot; reuse that full command below if `nanobot` is not on `PATH`.
 
 To preview the plan without changing your environment, pass `--dry-run`; combine it with `--dev` when you want to preview the main-branch install.
 
@@ -240,7 +240,7 @@ For one request and an immediate exit, use:
 nanobot agent -m "Hello!"
 ```
 
-The one-shot form is useful for a quick provider check, shell scripts, and local automation. If you have not configured a model yet, run `nanobot onboard --wizard` first.
+The one-shot form is useful for a quick provider check, shell scripts, and local automation. If you have not configured a model yet, run `nanobot webui` and open **Settings → Models** first.
 
 Need manual JSON, another device on your LAN, or help with provider/model matching? Continue with [Install and Quick Start](./docs/quick-start.md), [WebUI](./docs/webui.md), or [Troubleshooting](./docs/troubleshooting.md).
 

docs/README.md

@@ -15,11 +15,11 @@ Repository docs follow the current source tree and can be newer than the latest
 The recommended first-run path is:
 
 1. Install nanobot.
-2. Choose **Quick Start** in `nanobot onboard --wizard`.
+2. Let the installer open `nanobot webui` on a fresh local desktop.
-3. Run `nanobot gateway` and open `http://127.0.0.1:8765`.
+3. Configure a provider and model in **Settings → Models**.
 4. Send `Hello!` before configuring anything else.
 
-Most people do not need to edit JSON for the first run. The wizard handles the initial provider, model, and local WebUI settings. Current source versions also provide `nanobot webui` to start the gateway and open the browser in one step. After the WebUI opens, use **Settings** for models and built-in capabilities, **Settings → Channels** for chat apps, and **Apps** for CLI App or MCP integrations.
+Most people do not need to edit JSON for the first run. The WebUI handles the initial provider, model, and local browser settings. SSH, headless, existing-config, and older-release installs retain `nanobot onboard --wizard` as a terminal fallback. After the WebUI opens, use **Settings** for models and built-in capabilities, **Settings → Channels** for chat apps, and **Apps** for CLI App or MCP integrations.
 
 ## Add One Capability
 

docs/cli-reference.md

@@ -95,7 +95,7 @@ Interactive mode exits with `exit`, `quit`, `/exit`, `/quit`, `:q`, or `Ctrl+D`.
 | `nanobot webui --no-open` | Prepare and start the WebUI without opening a browser |
 | `nanobot webui --port <port>` | Set the WebUI/WebSocket port |
 | `nanobot webui --gateway-port <port>` | Override the gateway health port |
-| `nanobot webui --yes` | Apply safe localhost WebUI defaults without confirmation; provider credentials still require interactive setup |
+| `nanobot webui --yes` | Apply safe localhost WebUI defaults without confirmation; configure provider credentials in **Settings → Models** |
 
 First-run WebUI setup binds to `127.0.0.1` by default. Use manual configuration and a WebUI password before exposing the WebSocket channel beyond localhost.
 

docs/configuration.md

@@ -201,7 +201,7 @@ These variables are process-level switches. Set them in the same terminal, servi
 |----------|---------|-------------|
 | `NANOBOT_BIN_DIR` | `$HOME/.local/bin` | Installer launcher directory on macOS/Linux. |
 | `NANOBOT_VENV` | `$HOME/.nanobot/venv` | Managed virtual environment path used by the installer fallback. |
-| `NANOBOT_SKIP_WIZARD` | unset | Set to `1` to skip `nanobot onboard --wizard` after one-command install. |
+| `NANOBOT_SKIP_WIZARD` | unset | Set to `1` to skip automatic WebUI or wizard setup after one-command install. |
 | `NANOBOT_SKIP_WEBUI_BUILD` | unset | Set to `1` to skip bundling the WebUI during package builds. |
 | `NANOBOT_FORCE_WEBUI_BUILD` | unset | Set to `1` to rebuild the bundled WebUI even when `nanobot/web/dist/index.html` already exists. |
 | `NANOBOT_EXTRAS` | unset | Docker build argument containing comma-separated Python extras such as `bedrock`. |

docs/quick-start.md

@@ -16,7 +16,7 @@ Git is only needed for a source install. The published package already contains
 
 ## 1. Install nanobot
 
-The recommended installer keeps nanobot out of the system Python environment and opens the setup wizard when installation finishes.
+The recommended installer keeps nanobot out of the system Python environment. On a fresh local desktop, it starts the WebUI when installation finishes.
 
 **macOS / Linux**
 
@@ -34,31 +34,34 @@ The installer chooses an active virtual environment, `uv`, `pipx`, or a managed
 
 If you prefer to inspect the scripts first, open [`install.sh`](../scripts/install.sh) or [`install.ps1`](../scripts/install.ps1).
 
-## 2. Complete Quick Start
+## 2. Configure Your Model
 
-The installer opens `nanobot onboard --wizard`. Choose **Quick Start** and follow the prompts:
+Keep the installer terminal open. The browser opens the local WebUI; go to **Settings → Models** and:
 
 1. Choose the provider or endpoint that owns your credential.
-2. Enter its API key or base URL when requested.
+2. Enter its API key or base URL when required.
-3. Enter a model ID that the same provider can run.
+3. Create or select a model preset using a model ID that provider can run.
-4. Let Quick Start enable the local WebUI.
+4. Save the configuration.
-5. Set a WebUI password and review the summary.
 
-Quick Start creates or updates:
+The WebUI launcher creates or updates:
 
 | Path | Purpose |
 |---|---|
 | `~/.nanobot/config.json` | Provider, model, WebUI, channel, tool, and runtime settings |
 | `~/.nanobot/workspace/` | Sessions, memory, skills, automations, and generated files |
 
-If the installer did not open the wizard, run it yourself:
+If the installer did not open the browser, run:
+
+```bash
+nanobot webui
+```
+
+SSH, headless, existing-config, and older-release installs retain the terminal setup path:
 
 ```bash
 nanobot onboard --wizard
 ```
 
-Current source versions also provide `nanobot webui`. When run without a usable model, that launcher offers the same Quick Start flow before starting the browser.
-
 ## 3. Check the Setup
 
 ```bash
@@ -75,11 +78,7 @@ Most other providers can say `not set`. This command validates local setup but d
 
 ## 4. Get the First Reply
 
-```bash
+If the installer-started WebUI is no longer running, run `nanobot webui` again. Leave that terminal open; the first-run WebUI is bound to localhost, so other devices on your network cannot reach it.
-nanobot gateway
-```
-
-Quick Start has already prepared the local WebSocket channel. Leave the gateway terminal open and visit `http://127.0.0.1:8765`; the first-run WebUI is bound to localhost, so other devices on your network cannot reach it. On current source versions, you can run `nanobot webui` instead to perform the local WebUI checks, start the gateway, and open the browser automatically.
 
 Send:
 
@@ -131,20 +130,20 @@ After the first reply works, add one capability and test again:
 
 ## Other Install Methods
 
-Use one method, then continue at [Complete Quick Start](#2-complete-quick-start).
+Use one method, then continue at [Configure Your Model](#2-configure-your-model).
 
 **uv**
 
 ```bash
 uv tool install nanobot-ai
-nanobot onboard --wizard
+nanobot webui
 ```
 
 **pip in a virtual environment**
 
 ```bash
 python -m pip install nanobot-ai
-nanobot onboard --wizard
+nanobot webui
 ```
 
 If pip reports `externally-managed-environment`, use the recommended installer, `uv tool install nanobot-ai`, `pipx install nanobot-ai`, or create a virtual environment. Do not force a system-wide install.
@@ -157,7 +156,7 @@ If pip reports `externally-managed-environment`, use the recommended installer,
 git clone https://github.com/HKUDS/nanobot.git
 cd nanobot
 python -m pip install .
-nanobot onboard --wizard
+nanobot webui
 ```
 
 On Windows, if `python -m pip install .` reports that it cannot launch `npm`, run `cd webui`, `npm.cmd install --package-lock=false`, `npm.cmd run build`, and `cd ..` in order, then retry the install.
@@ -172,7 +171,7 @@ pipx run --spec nanobot-ai nanobot --version
 ~/.nanobot/venv/bin/python -m nanobot --version
 ```
 
-On Windows, the managed-environment form is `& "$HOME\.nanobot\venv\Scripts\python.exe" -m nanobot --version`. Replace `--version` with `onboard --wizard`, `gateway`, or any other arguments you need. Use plain `python -m nanobot` only when that Python executable belongs to the environment where nanobot was installed.
+On Windows, the managed-environment form is `& "$HOME\.nanobot\venv\Scripts\python.exe" -m nanobot --version`. Replace `--version` with `webui`, `onboard --wizard`, or any other arguments you need. Use plain `python -m nanobot` only when that Python executable belongs to the environment where nanobot was installed.
 
 ## Manual Configuration Fallback
 

docs/start-without-technical-background.md

@@ -70,53 +70,35 @@ curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.
 irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex
 ```
 
-The installer downloads the stable nanobot package into an isolated Python environment and opens the setup wizard. It can take a few minutes on the first run. When it finishes, it prints the exact command it used to run nanobot. Keep that command: if `nanobot` is not found later, reuse the whole printed command instead of switching to a different Python command.
+The installer downloads the stable nanobot package into an isolated Python environment. On a fresh local desktop, it then starts the WebUI and opens your browser. This can take a few minutes on the first run. Keep the terminal open. It prints the exact command used to run nanobot; if `nanobot` is not found later, reuse that whole command instead of switching to a different Python command.
 
 If your organization blocks downloaded install scripts, use the [alternative install methods](./quick-start.md#other-install-methods) or ask your administrator to review the scripts first.
 
-## 4. Follow Quick Start
+## 4. Configure Your Model in the WebUI
 
-The wizard shows a menu similar to:
+In the browser, open **Settings → Models**. Then:
-
-```text
-> What would you like to do?
-  [Q] Quick Start
-  [A] Advanced Settings
-  [X] Exit
-```
-
-Choose **Quick Start**. Use the arrow keys to highlight an option and press `Enter`.
-
-The wizard asks for only the information needed for the first reply:
 
 1. Choose your provider.
-2. Choose an endpoint option if the provider offers several plans.
+2. Enter its API key and base URL when required.
-3. Paste the API key if asked.
+3. Create or select a model preset.
-4. Enter the base URL if asked.
+4. Enter a model ID available to your provider account.
-5. Enter a model ID.
+5. Save the configuration.
-6. Confirm the local WebUI setup.
-7. Choose a WebUI password.
-8. Review the summary and save.
 
-When you paste a password or API key, the terminal may hide the characters. That is normal.
+Treat every API key like a password. Do not include it in screenshots or support requests.
 
-If the installer finishes without opening the wizard and `nanobot` is available, run:
+If the installer finishes without opening the browser and `nanobot` is available, run:
 
 ```bash
-nanobot onboard --wizard
+nanobot webui
 ```
 
-If the terminal cannot find `nanobot`, take the exact command printed by the installer and replace its final arguments with `onboard --wizard`. That command may begin with `uv tool run`, `pipx run`, or the full path to nanobot's private Python environment.
+If the terminal cannot find `nanobot`, take the exact command printed by the installer and replace its final arguments with `webui`. That command may begin with `uv tool run`, `pipx run`, or the full path to nanobot's private Python environment.
 
-## 5. Open the Browser
+On SSH, a computer without a desktop, an existing configuration, or an older nanobot release, the installer may open the terminal wizard instead. Choose **Quick Start** there and follow its prompts.
 
-Run:
+## 5. Get the First Reply
 
-```bash
+Leave the WebUI terminal open. If the browser did not open automatically, visit `http://127.0.0.1:8765`.
-nanobot gateway
-```
-
-Leave the terminal open, then open `http://127.0.0.1:8765` in your browser. Enter the WebUI password from the wizard if the browser asks for it. Current source versions also provide `nanobot webui`, which starts the gateway and opens the browser automatically.
 
 Send this message:
 
@@ -143,7 +125,7 @@ Do not configure every feature immediately. Choose one next goal:
 
 Repository docs show the current development version. If your stable package does not yet show **Settings → Channels**, use the [Chat Apps guide](./chat-apps.md) or update to a release that includes it.
 
-Some runtime changes ask you to restart nanobot. Use the restart action shown by the WebUI, or return to the terminal, press `Ctrl+C`, and run `nanobot gateway` again.
+Some runtime changes ask you to restart nanobot. Use the restart action shown by the WebUI, or return to the terminal, press `Ctrl+C`, and run `nanobot webui` again.
 
 For a chat platform's account, bot, token, or permission prerequisites, use the [Chat Apps guide](./chat-apps.md). For local models and provider-specific recipes, use the [Provider Cookbook](./provider-cookbook.md).
 
@@ -175,7 +157,7 @@ Continue with the full [Troubleshooting guide](./troubleshooting.md) for an orde
 Run:
 
 ```bash
-nanobot gateway
+nanobot webui
 ```
 
-Leave that terminal open and visit `http://127.0.0.1:8765`. To stop nanobot, return to the terminal and press `Ctrl+C`. Use `nanobot gateway --background` only after the normal foreground start works; then manage it with `nanobot gateway status`, `logs`, `restart`, and `stop`.
+Leave that terminal open while you use nanobot. To stop it, return to the terminal and press `Ctrl+C`. Use `nanobot webui --background` only after the normal foreground start and model setup work; then manage it with `nanobot gateway status`, `logs`, `restart`, and `stop`.

scripts/install.ps1

@@ -42,7 +42,7 @@ function Show-Usage {
     Write-Host ""
     Write-Host "By default this installs or upgrades nanobot-ai from PyPI."
     Write-Host "Use --dev to install from the current main branch on GitHub."
-    Write-Host "Use --dry-run to print what would happen without installing or starting the wizard."
+    Write-Host "Use --dry-run to print what would happen without installing or starting setup."
 }
 
 function Test-Python {
@@ -133,6 +133,26 @@ function Get-NanobotCommand {
     }
 }
 
+function Test-FreshNanobotInstall {
+    $HomeDir = [Environment]::GetFolderPath([Environment+SpecialFolder]::UserProfile)
+    if (-not $HomeDir) {
+        return $false
+    }
+    return -not (Test-Path -LiteralPath (Join-Path $HomeDir ".nanobot\config.json"))
+}
+
+function Test-BrowserSession {
+    if ($env:SSH_CONNECTION -or $env:SSH_TTY -or -not [Environment]::UserInteractive) {
+        return $false
+    }
+
+    $CurrentSessionId = (Get-Process -Id $PID).SessionId
+    return @(
+        Get-Process -Name explorer -ErrorAction SilentlyContinue |
+            Where-Object { $_.SessionId -eq $CurrentSessionId }
+    ).Count -gt 0
+}
+
 function Install-WithActivePython {
     Write-Info "Detected an active virtual environment. Installing into it..."
     Ensure-Pip $Python
@@ -252,7 +272,10 @@ if ($DryRun) {
         Write-Info "Dry run: would run nanobot as: $VenvDir\Scripts\python.exe -m nanobot"
     }
     if ($env:NANOBOT_SKIP_WIZARD -eq "1") {
-        Write-Info "Dry run: would skip setup wizard because NANOBOT_SKIP_WIZARD=1."
+        Write-Info "Dry run: would skip automatic setup because NANOBOT_SKIP_WIZARD=1."
+    } elseif ((Test-FreshNanobotInstall) -and (Test-BrowserSession)) {
+        Write-Info "Dry run: would start the WebUI for this fresh desktop install."
+        Write-Info "Dry run: would fall back to the setup wizard for older releases."
     } else {
         Write-Info "Dry run: would run the setup wizard."
     }
@@ -294,11 +317,27 @@ if ($LASTEXITCODE -ne 0) {
 }
 
 if ($env:NANOBOT_SKIP_WIZARD -eq "1") {
-    Write-Info "Skipping setup wizard because NANOBOT_SKIP_WIZARD=1."
+    Write-Info "Skipping automatic setup because NANOBOT_SKIP_WIZARD=1."
-    Write-Info "Run this later: $(Get-NanobotCommand) onboard --wizard"
+    Write-Info "Run this later: $(Get-NanobotCommand) webui"
     return
 }
 
+if ((Test-FreshNanobotInstall) -and (Test-BrowserSession)) {
+    Invoke-Nanobot @("webui", "--help") *> $null
+    if ($LASTEXITCODE -eq 0) {
+        Write-Info "Starting nanobot WebUI..."
+        Write-Info "Configure your first provider and model in Settings > Models."
+        Write-Info "Run this later: $(Get-NanobotCommand) webui"
+        Invoke-Nanobot @("webui", "--yes")
+        if ($LASTEXITCODE -ne 0) {
+            Fail "WebUI did not start."
+        }
+        return
+    }
+    Write-Info "The installed release does not support nanobot webui yet."
+    Write-Info "Falling back to the setup wizard..."
+}
+
 Write-Info "Starting setup wizard..."
 Invoke-Nanobot @("onboard", "--wizard")
 if ($LASTEXITCODE -ne 0) {

scripts/install.sh

@@ -36,7 +36,7 @@ Usage: install.sh [--dev] [--dry-run]
 
 By default this installs or upgrades nanobot-ai from PyPI.
 Use --dev to install from the current main branch on GitHub.
-Use --dry-run to print what would happen without installing or starting the wizard.
+Use --dry-run to print what would happen without installing or starting setup.
 EOF
 }
 
@@ -104,6 +104,30 @@ nanobot_try_command() {
   esac
 }
 
+is_fresh_nanobot_install() {
+  [ -n "${HOME:-}" ] || return 1
+  [ ! -e "$HOME/.nanobot/config.json" ]
+}
+
+has_browser_session() {
+  if [ -n "${SSH_CONNECTION:-}${SSH_TTY:-}" ]; then
+    return 1
+  fi
+  if ! : 2>/dev/null < /dev/tty; then
+    return 1
+  fi
+
+  case "$(uname -s)" in
+    Darwin)
+      command -v launchctl >/dev/null 2>&1 &&
+        launchctl print "gui/$(id -u)" >/dev/null 2>&1
+      ;;
+    *)
+      [ -n "${DISPLAY:-}${WAYLAND_DISPLAY:-}" ]
+      ;;
+  esac
+}
+
 install_with_active_python() {
   info "Detected an active virtual environment. Installing into it..."
   ensure_pip "$python_bin" || return 1
@@ -225,7 +249,10 @@ if [ "$dry_run" = "1" ]; then
     info "Dry run: would run nanobot as: $venv_dir/bin/python -m nanobot"
   fi
   if [ "${NANOBOT_SKIP_WIZARD:-}" = "1" ]; then
-    info "Dry run: would skip setup wizard because NANOBOT_SKIP_WIZARD=1."
+    info "Dry run: would skip automatic setup because NANOBOT_SKIP_WIZARD=1."
+  elif is_fresh_nanobot_install && has_browser_session; then
+    info "Dry run: would start the WebUI for this fresh desktop install."
+    info "Dry run: would fall back to the setup wizard for older releases."
   else
     info "Dry run: would run the setup wizard."
   fi
@@ -264,11 +291,23 @@ info "Installed nanobot:"
 run_nanobot --version
 
 if [ "${NANOBOT_SKIP_WIZARD:-}" = "1" ]; then
-  info "Skipping setup wizard because NANOBOT_SKIP_WIZARD=1."
+  info "Skipping automatic setup because NANOBOT_SKIP_WIZARD=1."
-  info "Run this later: $(nanobot_try_command) onboard --wizard"
+  info "Run this later: $(nanobot_try_command) webui"
   exit 0
 fi
 
+if is_fresh_nanobot_install && has_browser_session; then
+  if run_nanobot webui --help >/dev/null 2>&1; then
+    info "Starting nanobot WebUI..."
+    info "Configure your first provider and model in Settings > Models."
+    info "Run this later: $(nanobot_try_command) webui"
+    run_nanobot webui --yes
+    exit 0
+  fi
+  info "The installed release does not support nanobot webui yet."
+  info "Falling back to the setup wizard..."
+fi
+
 if [ -t 0 ]; then
   info "Starting setup wizard..."
   run_nanobot onboard --wizard