mirror of
https://github.com/HKUDS/nanobot.git
synced 2026-06-15 15:24:06 +00:00
4a58b83acc
* docs: make onboarding friendlier for beginners * docs: build clearer documentation paths Maintainer edit: turn the onboarding follow-up into a layered docs structure for first-time setup, provider selection, troubleshooting, CLI reference, and source-level architecture. This keeps quick start focused while giving advanced users precise reference paths. * docs: render architecture flow with mermaid Maintainer edit: replace the ASCII architecture sketch with a GitHub-rendered Mermaid flowchart so the core runtime path is easier to scan in the PR and README docs. * docs: recommend model presets for model config Maintainer edit: make named modelPresets the primary model configuration path and expand fallback preset examples so string fallbacks are clearly preset names, not raw model IDs. * docs: document api base urls and langfuse setup Maintainer edit: explain when users need apiBase/base URL in quick start and provider docs, and add Langfuse tracing setup with troubleshooting links. * docs: use python module pip consistently Maintainer edit: keep install commands tied to the active Python interpreter by using python -m pip in the Azure optional dependency notes too. * docs: add non-technical getting started path Maintainer edit: add a wizard-first guide for users without terminal or JSON background, including a text TUI menu example and links from the main docs entrypoints. * docs: avoid hard-wrapped prose in user docs Maintainer edit: unwrap ordinary prose across user-facing documentation while preserving markdown structure, code blocks, tables, lists, and prompt/template files. * docs: keep desktop list continuations nested Maintainer edit: preserve list nesting after unwrapping prose in the desktop WebUI sync guide. * docs: add one-command installer Maintainer edit: add auditable macOS/Linux and Windows install scripts that install nanobot-ai and start the onboarding wizard, then document the commands in the main onboarding entrypoints. * docs: add installer dry run mode Maintainer edit: add --dry-run to the one-command installer scripts so users can preview Python detection, install source, pip command, and wizard behavior without changing their environment. * docs: clean installer error output Maintainer edit: make PowerShell installer failures print a concise Error: message instead of Write-Error call-site details. * docs: add provider setup cookbook Maintainer edit: add pasteable provider recipes for common hosted, local, fallback, runtime switching, and Langfuse setups, then link the cookbook from onboarding and troubleshooting entrypoints. * docs: address review feedback * docs: clarify reader paths * docs: explain terminal basics for beginners * docs: clarify wizard navigation * docs: avoid duplicate onboarding steps * docs: add setup status check * docs: explain status output * docs: remove provider recommendation wording * docs: explain status diagnostics * docs: reduce hard-wrapped guidance * docs: migrate config examples to presets * docs: clarify python command fallbacks * docs: improve installer failure recovery * docs: expand install troubleshooting * docs: cover installer download failures * docs: put stable install paths first * docs: add bundled webui quick path * docs: clarify provider-neutral setup * docs: clarify gateway setup for chat surfaces * docs: improve docs navigation paths * docs: add configuration quick jump * docs: clarify provider secret variables * chore: request PR review acknowledgement Empty commit: please read the PR review comments and reply on the PR to confirm that you have received them. This commit intentionally changes no files; it exists only to notify the remote Codex run so it can end its active goal. * docs: add README start here guide * docs: avoid provider recommendation wording * docs: guide next steps after first reply * docs: explain merging JSON snippets * docs: add CLI command chooser * docs: add configuration task map * docs: add deployment readiness guide * docs: simplify WebUI entry paths * docs: add provider recipe chooser * docs: fix provider factual references Update OpenRouter and LongCat model examples, align Bedrock guidance, and make fallback snippets schema-valid. Also correct group policy wording and image-generation provider lists to match the current code. * fix: keep PowerShell installer from closing caller shell * docs: mention self-guided configuration
104 lines
4.8 KiB
Markdown
104 lines
4.8 KiB
Markdown
# nanobot Desktop
|
|
|
|
Mac-first desktop app for running nanobot locally with the same product UI as the browser WebUI.
|
|
|
|
For users, the desktop app is a local wrapper around nanobot: it starts the engine for you, keeps config and chat state in the platform app data directory, and uses the shared WebUI for chat, settings, apps, skills, and workspace selection.
|
|
|
|
For contributors, this folder is a native host shell. It reuses the root WebUI build at `nanobot/web/dist`; it does not copy or fork `webui/src`. Electron owns the local engine lifecycle, exposes `window.nanobotHost` to the renderer, serves the `nanobot-app://` app protocol, and proxies `/api/*` plus `/webui/bootstrap` to a private Unix socket `nanobot desktop-gateway` process.
|
|
|
|
## What To Read
|
|
|
|
- Using or trying the app from source: start with the development commands below.
|
|
- Changing desktop behavior: read [`docs/development.md`](docs/development.md).
|
|
- Adding native host capabilities: read [`docs/host-contract.md`](docs/host-contract.md).
|
|
- Keeping browser WebUI and desktop aligned: read [`docs/webui-sync.md`](docs/webui-sync.md).
|
|
|
|
## Development
|
|
|
|
This section is for contributors working from a source checkout.
|
|
|
|
```sh
|
|
cd desktop
|
|
bun run dev:webui
|
|
```
|
|
|
|
In another terminal:
|
|
|
|
```sh
|
|
cd desktop
|
|
bun run dev:app
|
|
```
|
|
|
|
`dev:app` points Electron at the Vite dev server so WebUI changes hot reload. For source checkouts, the app uses `python3` by default and injects the repo root into `PYTHONPATH`. Packaged builds look for a bundled interpreter at `Resources/nanobot-engine/bin/python3`.
|
|
|
|
## Engine Bundle
|
|
|
|
Release builds prepare `resources/nanobot-engine/` from a macOS `python-build-standalone` archive before running `electron-builder`. By default the script discovers the latest `astral-sh/python-build-standalone` CPython 3.12 `install_only` asset for the requested architecture.
|
|
|
|
```sh
|
|
cd desktop
|
|
bun run make:mac:arm64
|
|
bun run make:mac:x64
|
|
```
|
|
|
|
Useful overrides:
|
|
|
|
- `NANOBOT_DESKTOP_ARCH=arm64|x64`
|
|
- `NANOBOT_DESKTOP_PYTHON_VERSION=3.12`
|
|
- `PYTHON_STANDALONE_RELEASE=20260510`
|
|
- `PYTHON_STANDALONE_TARBALL=/path/to/archive.tar.gz`
|
|
- `PYTHON_STANDALONE_URL=https://.../cpython-...tar.gz`
|
|
- `NANOBOT_WHEELHOUSE=/path/to/wheels` to install from a locked wheelhouse
|
|
|
|
The script installs the current checkout's `nanobot-ai[api]` into the bundled runtime and writes `nanobot-engine.json` for diagnostics.
|
|
|
|
## Updating Builds
|
|
|
|
The native host does not copy the WebUI source or fork the Python agent code. A release bundle is assembled from the current repository state:
|
|
|
|
1. Build the shared WebUI:
|
|
|
|
```sh
|
|
bun run build --prefix webui
|
|
```
|
|
|
|
`electron-builder` packages the resulting `nanobot/web/dist` directory as `Resources/nanobot-webui`.
|
|
|
|
2. Prepare the bundled Python engine:
|
|
|
|
```sh
|
|
cd desktop
|
|
NANOBOT_DESKTOP_ARCH=arm64 bun run prepare-engine
|
|
```
|
|
|
|
The script installs the current checkout's `nanobot-ai[api]` package into `resources/nanobot-engine/`, so agent, provider, tool, WebSocket, and config changes flow into the next desktop build automatically.
|
|
|
|
3. Build the desktop app and DMG:
|
|
|
|
```sh
|
|
bun run make:mac:arm64
|
|
bun run make:mac:x64
|
|
```
|
|
|
|
User data is not stored in the app bundle. Config, sessions, logs, workspace state, and the default workspace remain under the platform app data directory, so updating the app replaces code without overwriting local user state.
|
|
|
|
## Runtime Contract
|
|
|
|
- User data lives under Electron's platform app data directory. In development this is usually `~/Library/Application Support/@nanobot/desktop/` on macOS; packaged builds use the packaged app name.
|
|
- Fresh installs start the private engine directly. The Python desktop gateway creates the first `config.json` with defaults, then shared WebUI settings own provider, model, and credential setup.
|
|
- The gateway listens on a per-user Unix socket in the app data directory and uses a transient secret.
|
|
- The gateway starts with only the WebSocket local channel enabled and does not serve the WebUI static bundle.
|
|
- The renderer loads assets through `nanobot-app://app/...`; browser users cannot open the native UI from a localhost port.
|
|
- WebSocket traffic uses the generic `nanobot-host://engine/...` URL, is bridged over Electron IPC, and still uses the short-lived token minted by `/webui/bootstrap`.
|
|
- Host IPC only accepts the trusted app origin, and socket bridging only accepts the `nanobot-host://engine/...` scheme.
|
|
- Native WebUI responses include a restrictive Content Security Policy.
|
|
- WebUI talks only to the generic `window.nanobotHost` contract. Product-specific native behavior stays in this folder.
|
|
|
|
Generated release artifacts, node modules, and bundled runtimes remain ignored so the tracked desktop package stays source-only.
|
|
|
|
See also:
|
|
|
|
- [`docs/development.md`](docs/development.md)
|
|
- [`docs/host-contract.md`](docs/host-contract.md)
|
|
- [`docs/webui-sync.md`](docs/webui-sync.md)
|