feat: open WebUI after fresh desktop install
This commit is contained in:
chengyongru
chengyongru
@@ -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).
|
||||
|
||||
|
||||
+3
-3
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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`. |
|
||||
|
||||
+20
-21
@@ -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
|
||||
|
||||
|
||||
@@ -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`.
|
||||
|
||||
+43
-4
@@ -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) {
|
||||
|
||||
+43
-4
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user