Agent Zero Desktop

Electron wrapper for Agent Zero — a cross-platform native desktop app.

Structure

├── main.js              # Main process: window, Docker, IPC, menu
├── preload.js           # Secure IPC bridge (contextBridge)
├── docker.js            # Docker container lifecycle
├── package.json         # Electron 40.x + electron-builder
├── lib/
│   ├── store.js         # JSON config persistence
│   └── credentials.js   # Encrypted credential storage (safeStorage)
├── scripts/
│   └── build-icons.js   # Generate platform icons from SVG
├── renderer/
│   ├── app/
│   │   ├── app.html     # Unified page: loading / setup / error views
│   │   ├── app.css      # Styles (a0 dark theme)
│   │   └── app.js       # View logic + IPC listeners
│   └── titlebar/
│       └── titlebar.js  # Injected titlebar + credential management
├── assets/icons/        # Generated icons (do not edit)
└── build/
    └── entitlements.mac.plist

Requirements

• Node.js 20+
• Docker Desktop (for local mode)
• macOS 12+ / Windows 10+ / Linux

Quick Start

npm install
npm run build:icons   # First time / after icon.svg changes
npm run dev           # Development mode (with DevTools)

App Flow

First run: Loading → Setup → Loading → WebUI

Subsequent runs: Loading → WebUI

Single-window architecture — the same window transitions between views (no size changes or flicker).

Credential Memory

Login credentials are encrypted via Electron safeStorage (macOS Keychain / Windows DPAPI / Linux kwallet) and persisted locally:

1. Save: On login form submit, credentials are captured before the POST redirect. After successful login, a "Save Password?" prompt appears on the dashboard page. Saved passwords are encrypted at the OS level.
2. Auto-fill: On subsequent visits to the login page, saved credentials are automatically filled into empty username/password fields.

Connection Modes

Mode	Description
Local	Starts a Docker container automatically, polls /health until ready
Remote	Connects directly to a remote Agent Zero server URL

Keyboard Shortcuts

Shortcut	Action
Cmd+N	New Chat
Cmd+D	Dashboard
Alt+Cmd+C	Clear Chat
Cmd+S	Export Chat
Cmd+O	Import Chat
Cmd+P	Pause / Resume Agent
Cmd+J	Nudge Agent
Cmd+K	Import Knowledge
Cmd+F	File Browser
Cmd+B	Toggle Sidebar
Cmd+Shift+L	Toggle Theme
Cmd+,	Settings
Cmd+Up	Scroll to Top
Cmd+Down	Scroll to Bottom
Alt+Up	Previous User Message
Alt+Down	Next User Message

Build

npm run build:mac     # macOS (Universal Binary)
npm run build:win     # Windows (NSIS)
npm run build:linux   # Linux (AppImage + deb)

Output in dist/.

Code Signing (macOS)

export CSC_LINK=/path/to/cert.p12
export CSC_KEY_PASSWORD=your_password
export APPLE_ID=your@apple.com
export APPLE_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx
export APPLE_TEAM_ID=XXXXXXXXXX
npm run build:mac

Design Principles

• No a0 source modifications — Electron acts as a native container
• Dark theme — matches a0 WebUI (#131313 background, #cf6679 accent)
• macOS — titleBarStyle: "hidden" preserves native traffic lights
• Windows/Linux — Injected custom window control buttons
• Security — contextIsolation: true, nodeIntegration: false