mirror of
https://github.com/HKUDS/nanobot.git
synced 2026-08-08 05:18:49 +03:00
115 lines
4.1 KiB
Markdown
115 lines
4.1 KiB
Markdown
# nanobot Desktop
|
|
|
|
Electron package for the Mac-first nanobot native app.
|
|
|
|
This folder is a 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.
|
|
|
|
## Development
|
|
|
|
```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)
|