diff --git a/README.md b/README.md index f0fdbb55..c2e0b0d5 100644 --- a/README.md +++ b/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). diff --git a/docs/README.md b/docs/README.md index e916f5cf..8517e885 100644 --- a/docs/README.md +++ b/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`. -3. Run `nanobot gateway` and open `http://127.0.0.1:8765`. +2. Let the installer open `nanobot webui` on a fresh local desktop. +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 diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 1db77c3b..7e36a6c3 100644 --- a/docs/cli-reference.md +++ b/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 ` | Set the WebUI/WebSocket port | | `nanobot webui --gateway-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. diff --git a/docs/configuration.md b/docs/configuration.md index b1c6c308..3f461a07 100644 --- a/docs/configuration.md +++ b/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`. | diff --git a/docs/quick-start.md b/docs/quick-start.md index 6d4b02fb..92add625 100644 --- a/docs/quick-start.md +++ b/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. -3. Enter a model ID that the same provider can run. -4. Let Quick Start enable the local WebUI. -5. Set a WebUI password and review the summary. +2. Enter its API key or base URL when required. +3. Create or select a model preset using a model ID that provider can run. +4. Save the configuration. -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 -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. +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. 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 diff --git a/docs/start-without-technical-background.md b/docs/start-without-technical-background.md index f6921df0..7c588383 100644 --- a/docs/start-without-technical-background.md +++ b/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: - -```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: +In the browser, open **Settings → Models**. Then: 1. Choose your provider. -2. Choose an endpoint option if the provider offers several plans. -3. Paste the API key if asked. -4. Enter the base URL if asked. -5. Enter a model ID. -6. Confirm the local WebUI setup. -7. Choose a WebUI password. -8. Review the summary and save. +2. Enter its API key and base URL when required. +3. Create or select a model preset. +4. Enter a model ID available to your provider account. +5. Save the configuration. -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 -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. +Leave the WebUI terminal open. If the browser did not open automatically, visit `http://127.0.0.1:8765`. 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`. diff --git a/scripts/install.ps1 b/scripts/install.ps1 index 328eb6dc..bbbca710 100644 --- a/scripts/install.ps1 +++ b/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 "Run this later: $(Get-NanobotCommand) onboard --wizard" + Write-Info "Skipping automatic setup because NANOBOT_SKIP_WIZARD=1." + 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) { diff --git a/scripts/install.sh b/scripts/install.sh index b83b9969..0cb61666 100755 --- a/scripts/install.sh +++ b/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 "Run this later: $(nanobot_try_command) onboard --wizard" + info "Skipping automatic setup because NANOBOT_SKIP_WIZARD=1." + 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