AstrBot/desktop/README.md

AstrBot Desktop (Electron)

This document describes how to build the Electron desktop app from source.

What This Package Contains

• Electron desktop shell (desktop/main.js)
• Bundled WebUI static files (desktop/resources/webui)
• App assets (desktop/assets)

Current behavior:

• Backend executable is bundled in the installer/package.
• App startup checks backend availability and auto-starts bundled backend when needed.
• Runtime data is stored under ~/.astrbot by default, not as a full AstrBot source project.

Prerequisites

• Python environment ready in repository root (uv available)
• Node.js available
• pnpm available

Desktop dependency management uses pnpm with a lockfile:

• desktop/pnpm-lock.yaml
• pnpm --dir desktop install --frozen-lockfile

Build From Scratch

Run commands from repository root:

uv sync
pnpm --dir dashboard install
pnpm --dir dashboard build
pnpm --dir desktop install --frozen-lockfile
pnpm --dir desktop run dist:full

Output files are generated under:

• desktop/dist/

Local Run (Development)

Start backend first:

uv run main.py

Start Electron shell:

pnpm --dir desktop run dev

Notes

• dist:full runs WebUI build + backend build + Electron packaging.
• In packaged app mode, backend data root defaults to ~/.astrbot (can be overridden by ASTRBOT_ROOT).
• Backend build uses uv run --with pyinstaller ..., so no manual PyInstaller install is required.

Runtime Directory Layout

By default (ASTRBOT_ROOT not set), packaged desktop app uses this layout:

~/.astrbot/
  data/
    config/         # Main configuration
    plugins/        # Installed plugins
    plugin_data/    # Plugin persistent data
    site-packages/  # Plugin dependency installation target in packaged mode
    temp/           # Runtime temp files
    skills/         # Skill-related runtime data
    knowledge_base/ # Knowledge base files
    backups/        # Backup data

The app does not store a full AstrBot source tree in home directory.

Troubleshooting

Startup behavior:

• Packaged app shows a local startup page first, then switches to dashboard after backend is reachable.
• If startup page never switches, check logs and timeout settings below.

Runtime logs:

• Electron shell log: ~/.astrbot/logs/electron.log
• Backend stdout/stderr log: ~/.astrbot/logs/backend.log
• Both files rotate by size by default: 20MB per file, keep 3 backups.
• Electron log rotation envs:
  • ASTRBOT_ELECTRON_LOG_MAX_MB
  • ASTRBOT_ELECTRON_LOG_BACKUP_COUNT
• Backend log rotation envs:
  • ASTRBOT_BACKEND_LOG_MAX_MB
  • ASTRBOT_BACKEND_LOG_BACKUP_COUNT
• Rotation debug logging:
  • ASTRBOT_LOG_ROTATION_DEBUG=1 (or NODE_ENV=development) to print filesystem errors from rotation operations.
• On backend startup failure, the app dialog also shows the backend reason and backend log path.

Timeout and loading controls:

• ASTRBOT_BACKEND_TIMEOUT_MS controls how long Electron waits for backend reachability.
• In packaged mode, default is 0 (auto mode with a 5-minute safety cap).
• In development mode, default is 20000.
• If backend startup times out, app shows startup failure dialog and exits.
• ASTRBOT_DASHBOARD_TIMEOUT_MS controls dashboard page load wait time after backend is ready (default 20000).
• If you see Unable to load the AstrBot dashboard., increase ASTRBOT_DASHBOARD_TIMEOUT_MS.

Startup page locale:

• Startup page language follows cached dashboard locale in ~/.astrbot/data/desktop_state.json.
• Supported startup locales are zh-CN and en-US.
• Remove that file to reset locale fallback behavior.

Backend auto-start:

• ASTRBOT_BACKEND_AUTO_START=0 disables Electron-managed backend startup.
• When disabled, backend must already be running at ASTRBOT_BACKEND_URL before launching app.

If Electron download times out on restricted networks, configure mirrors before install:

export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
export ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"
pnpm --dir desktop install --frozen-lockfile