Humanity in a Box

Native-feeling Electron + local web stack for an offline Ubuntu knowledge hotspot.

What is included (MVP + V1 in progress)

• apps/desktop: Electron desktop admin shell with hardened preload IPC and local service controls.
• apps/server: Local backend daemon for content packs, jobs, search index, app registry, diagnostics, and Ollama integration.
• apps/admin-ui: Browser-based admin console (also embeddable/launchable from desktop).
• apps/portal: Mobile-first learner portal for phones/laptops on the same LAN.
• packages/shared: Shared contracts for desktop IPC and core types.
• packages/ui-tokens: Shared design tokens and accessibility-safe UI primitives.

Implemented capabilities

• Offline learner portal with local search and content browsing.
• Content pack ingestion from URL and local path with indexing + citations.
• Plugin app surface (built-ins: files, notes) with portal launch tiles.
• Local assistant via Ollama (/api/chat, model status/list/pull/config).
• Admin network mode control:
  • LAN mode (default)
  • Hotspot mode (best effort) via nmcli for Ubuntu hosts
• Desktop kiosk mode:
  • Startup via DESKTOP_KIOSK_MODE=1
  • Runtime toggle via secure IPC
  • Kiosk keyguard blocks common escape shortcuts.

Security defaults

• Electron uses contextIsolation: true, nodeIntegration: false, sandbox: true.
• IPC uses allowlisted channels and runtime payload validation.
• Admin APIs require x-admin-password (or bearer token compatibility path).
• Remote admin is off by default (ENABLE_REMOTE_ADMIN=false).

Quick start

npm install
npm run dev:stack

One-command desktop installer (build + install + verify):

./install.sh
# or:
npm run install:one-command

Services started by dev:stack:

• Backend API: http://127.0.0.1:8787
• Admin UI: http://127.0.0.1:5174
• Learner Portal: http://127.0.0.1:5175
• Electron Desktop shell

Useful scripts

• npm run dev:backend real backend daemon.
• npm run dev:admin admin UI Vite app.
• npm run dev:portal learner portal Vite app.
• npm run dev:desktop Electron desktop shell.
• npm run build builds all workspace packages/apps.
• npm run build -w @humanity/desktop builds the desktop bundle (apps/desktop/out).
• npm exec -w @humanity/desktop electron-builder -- --config electron-builder.yml --linux deb packages a Debian installer into apps/desktop/release/.
• npm run typecheck runs workspace typechecks when present.
• npm run test:e2e:install installs Playwright Chromium runtime.
• npm run test:e2e runs end-to-end install/search/chat/portal tests.

Debian package workflow (Ubuntu/Debian)

Build .deb:

npm run build:desktop:linux

Expected artifact path: apps/desktop/release/humanity-in-a-box-<version>-<arch>.deb

Install:

npm run install:desktop:deb
# or directly:
sudo apt install ./apps/desktop/release/humanity-in-a-box-<version>-<arch>.deb

Uninstall:

sudo apt remove humanity-in-a-box
# optional: remove package and system config files
sudo apt purge humanity-in-a-box

Dependency behavior:

• Preferred: apt install ./path/to/package.deb installs the package and resolves missing dependencies from configured APT repositories.
• If you use dpkg -i, resolve missing dependencies afterward:

sudo dpkg -i ./apps/desktop/release/humanity-in-a-box-<version>-<arch>.deb
sudo apt --fix-broken install

Startup diagnostics (desktop app):

• Main-process startup log: ~/.humanity-in-a-box/desktop-startup.log
• Chromium log: ~/.humanity-in-a-box/chromium.log
• Override paths with:
  • HIB_DESKTOP_LOG_PATH
  • HIB_CHROMIUM_LOG_PATH

Core backend env vars

• HOST (default 0.0.0.0)
• PORT (default 8787)
• DATA_ROOT (default ./data)
• LIBRARY_ROOT (default ./data/library)
• DB_PATH (default ./data/app.sqlite)
• ADMIN_PASSWORD (optional; if unset, first-run setup is required via /api/admin/setup)
• ENABLE_REMOTE_ADMIN (default false)
• OLLAMA_BASE_URL (default http://127.0.0.1:11434)
• OLLAMA_DEFAULT_MODEL (default llama3.2:3b)
• ASSISTANT_WRITE_REQUIRES_ADMIN (default false)

Desktop env vars

• BACKEND_URL, ADMIN_URL, PORTAL_URL
• BACKEND_DEV_SCRIPT, ADMIN_DEV_SCRIPT, PORTAL_DEV_SCRIPT
• DESKTOP_ASSUME_RUNNING_SERVICES=1
• DESKTOP_KIOSK_MODE=1 to start desktop shell in kiosk mode

Notes

• Content pack install supports URL archives and local-path imports with manifest fallback.
• Search is local SQLite FTS5 over indexed pack content.
• AI assistant answers are grounded with local citations and fallback behavior when Ollama is unavailable.
• Hotspot control requires nmcli available on host and sufficient privileges.