1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413# OpenFang Desktop App
The OpenFang Desktop App is a native desktop wrapper built with [Tauri 2.0](https://v2.tauri.app/) that packages the entire OpenFang Agent OS into a single, installable application. Instead of running a CLI daemon and opening a browser, users get a native window with system tray integration, OS notifications, and single-instance enforcement -- all powered by the same kernel and API server that the headless deployment uses.
**Crate:** `openfang-desktop`
**Identifier:** `ai.openfang.desktop`
**Product name:** OpenFang
---
## Architecture
The desktop app follows a straightforward embedded-server pattern:
```
+-------------------------------------------+
| Tauri 2.0 Process |
| |
| +-----------+ +--------------------+ |
| | Main | | Background Thread | |
| | Thread | | ("openfang-server")| |
| | | | | |
| | WebView | | tokio runtime | |
| | Window |--->| axum API server | |
| | (main) | | channel bridges | |
| | | | background agents | |
| | System | | | |
| | Tray | | OpenFang Kernel | |
| +-----------+ +--------------------+ |
| | | |
| | http://127.0.0.1:{port} |
| +------------------------------------
+-------------------------------------------+
```
### Startup Sequence
1. **Tracing init** -- `tracing_subscriber` is configured with `RUST_LOG` env, defaulting to `openfang=info,tauri=info`.
2. **Kernel boot** -- `OpenFangKernel::boot(None)` loads the default configuration (from `config.toml` or defaults), wrapped in `Arc`. `set_self_handle()` is called to enable self-referencing kernel operations.
3. **Port binding** -- A `std::net::TcpListener` binds to `127.0.0.1:0` on the main thread, which lets the OS assign a random free port. This ensures the port number is known before any window is created.
4. **Server thread** -- A dedicated OS thread named `"openfang-server"` is spawned. It creates its own `tokio::runtime::Builder::new_multi_thread()` runtime and runs:
- `kernel.start_background_agents()` -- heartbeat monitor, autonomous agents, etc.
- `run_embedded_server()` -- builds the axum router via `openfang_api::server::build_router()`, converts the `std::net::TcpListener` to a `tokio::net::TcpListener`, and serves with graceful shutdown.
5. **Tauri app** -- The Tauri builder is assembled with plugins, managed state, IPC commands, system tray, and a WebView window pointing at `http://127.0.0.1:{port}`.
6. **Event loop** -- Tauri runs its native event loop. On exit, `server_handle.shutdown()` is called to stop the embedded server and kernel.
### ServerHandle
The `ServerHandle` struct (defined in `src/server.rs`) manages the embedded server lifecycle:
```rust
pub struct ServerHandle {
pub port: u16,
pub kernel: Arc<OpenFangKernel>,
shutdown_tx: watch::Sender<bool>,
server_thread: Option<std::thread::JoinHandle<()>>,
}
```
- **`port`** -- The port the embedded server is listening on.
- **`kernel`** -- Shared reference to the kernel, also used by the Tauri app for IPC commands and notifications.
- **`shutdown_tx`** -- A `tokio::sync::watch` channel. Sending `true` triggers graceful shutdown of the axum server.
- **`server_thread`** -- Join handle for the background thread. `shutdown()` joins it to ensure clean termination.
Calling `shutdown()` sends the shutdown signal, joins the background thread, and calls `kernel.shutdown()`. The `Drop` implementation sends the shutdown signal as a best-effort fallback but does not block on the thread join.
### Graceful Shutdown
The axum server uses `with_graceful_shutdown()` wired to the watch channel:
```rust
let server = axum::serve(listener, app.into_make_service_with_connect_info::<SocketAddr>())
.with_graceful_shutdown(async move {
let _ = shutdown_rx.wait_for(|v| *v).await;
});
```
After the server shuts down, channel bridges (Telegram, Slack, etc.) are stopped via `bridge.stop().await`.
---
## Features
### System Tray
The system tray (defined in `src/tray.rs`) provides quick access without bringing up the main window:
| Menu Item | Behavior |
|-----------|----------|
| **Show Window** | Calls `show()`, `unminimize()`, and `set_focus()` on the main WebView window |
| **Open in Browser** | Reads the port from managed `PortState` and opens `http://127.0.0.1:{port}` in the default browser |
| **Agents: N running** | Disabled (info only) — shows current agent count |
| **Status: Running (uptime)** | Disabled (info only) — shows uptime in human-readable format |
| **Launch at Login** | Checkbox — toggles OS-level auto-start via `tauri-plugin-autostart` |
| **Check for Updates...** | Checks for updates, downloads, installs, and restarts if available. Shows notifications for progress/success/failure |
| **Open Config Directory** | Opens `~/.openfang/` in the OS file manager |
| **Quit OpenFang** | Logs the quit event and calls `app.exit(0)` |
The tray tooltip reads **"OpenFang Agent OS"**.
**Left-click on tray icon** shows the main window (same as "Show Window" menu item). This is implemented via `on_tray_icon_event` listening for `MouseButton::Left` with `MouseButtonState::Up`.
### Single-Instance Enforcement
On desktop platforms, `tauri-plugin-single-instance` prevents multiple copies of OpenFang from running simultaneously. When a second instance attempts to launch, the existing instance's main window is shown, unminimized, and focused:
```rust
#[cfg(desktop)]
{
builder = builder.plugin(tauri_plugin_single_instance::init(
|app, _args, _cwd| {
if let Some(w) = app.get_webview_window("main") {
let _ = w.show();
let _ = w.unminimize();
let _ = w.set_focus();
}
},
));
}
```
### Hide-to-Tray on Close
Closing the window does not quit the application. Instead, the window is hidden and the close event is suppressed:
```rust
.on_window_event(|window, event| {
#[cfg(desktop)]
if let tauri::WindowEvent::CloseRequested { api, .. } = event {
let _ = window.hide();
api.prevent_close();
}
})
```
To actually quit, use the **"Quit OpenFang"** option in the system tray menu.
### Native OS Notifications
The app subscribes to the kernel's event bus and forwards critical events as native desktop notifications using `tauri-plugin-notification`:
| Event | Notification Title | Body |
|-------|-------------------|------|
| `LifecycleEvent::Crashed` | "Agent Crashed" | `Agent {id} crashed: {error}` |
| `LifecycleEvent::Spawned` | "Agent Started" | `Agent "{name}" is now running` |
| `SystemEvent::HealthCheckFailed` | "Health Check Failed" | `Agent {id} unresponsive for {secs}s` |
All other events are silently skipped. The notification listener runs as an async task spawned via `tauri::async_runtime::spawn` and handles broadcast lag gracefully (logs a warning and continues).
---
## IPC Commands
Eleven Tauri IPC commands are registered, callable from the WebView frontend via `invoke()`:
### `get_port`
Returns the port number (`u16`) the embedded server is listening on.
```typescript
// Frontend usage
const port: number = await invoke("get_port");
```
### `get_status`
Returns a JSON object with runtime status:
```json
{
"status": "running",
"port": 8042,
"agents": 5,
"uptime_secs": 3600
}
```
- `agents` -- count of registered agents from `kernel.registry.list()`.
- `uptime_secs` -- seconds since the kernel state was initialized (via `Instant::now()` at startup).
### `get_agent_count`
Returns the number of registered agents (`usize`) as a simple integer.
```typescript
const count: number = await invoke("get_agent_count");
```
### `import_agent_toml`
Opens a native file picker for `.toml` files. Validates the selected file as an `AgentManifest`, copies it to `~/.openfang/agents/{name}/agent.toml`, and spawns the agent. Returns the agent name on success.
### `import_skill_file`
Opens a native file picker for skill files (`.md`, `.toml`, `.py`, `.js`, `.wasm`). Copies the file to `~/.openfang/skills/` and triggers a hot-reload of the skill registry.
### `get_autostart` / `set_autostart`
Check or toggle whether OpenFang launches at OS login. Uses `tauri-plugin-autostart` (launchd on macOS, registry on Windows, systemd on Linux).
### `check_for_updates`
Checks for available updates without installing. Returns an `UpdateInfo` object:
```json
{ "available": true, "version": "0.2.0", "body": "Release notes..." }
```
### `install_update`
Downloads and installs the latest update, then restarts the app. The command does not return on success (the app restarts). Returns an error string on failure.
```typescript
await invoke("install_update"); // App restarts if update succeeds
```
### `open_config_dir` / `open_logs_dir`
Opens `~/.openfang/` or `~/.openfang/logs/` in the OS file manager.
---
## Window Configuration
The main window is created programmatically in the `setup` closure (not via `tauri.conf.json`, which declares an empty `windows: []` array):
| Property | Value |
|----------|-------|
| Window label | `"main"` |
| Title | `"OpenFang"` |
| URL | `http://127.0.0.1:{port}` (external) |
| Inner size | 1280 x 800 |
| Minimum inner size | 800 x 600 |
| Position | Centered |
The window uses `WebviewUrl::External(...)` rather than a bundled frontend, because the WebView renders the axum-served UI.
### Auto-Updater
The app checks for updates 10 seconds after startup. If an update is available, it is downloaded, installed, and the app restarts automatically. Users can also trigger a manual check via the system tray.
**Flow:**
1. Startup check (10s delay) → `check_for_update()` → if available → notify user → `download_and_install_update()` → app restarts
2. Tray "Check for Updates" → same flow, with failure notification if install fails
**Configuration** (in `tauri.conf.json`):
- `plugins.updater.pubkey` — Ed25519 public key (must match the signing private key)
- `plugins.updater.endpoints` — URL to `latest.json` (hosted on GitHub Releases)
- `plugins.updater.windows.installMode` — `"passive"` (install without full UI)
**Signing:** Every release bundle is signed with `TAURI_SIGNING_PRIVATE_KEY` (GitHub Secret). The `tauri-action` generates `latest.json` containing download URLs and signatures for each platform.
See [Production Checklist](production-checklist.md) for key generation and setup instructions.
### CSP
The `tauri.conf.json` configures a Content Security Policy that allows connections to the local embedded server:
```
default-src 'self' http://127.0.0.1:* ws://127.0.0.1:*;
img-src 'self' data: http://127.0.0.1:*;
style-src 'self' 'unsafe-inline';
script-src 'self' 'unsafe-inline'
```
This permits the WebView to load content from the localhost API server while blocking external resource loading. The axum API server provides additional security headers middleware.
---
## Building
### Prerequisites
- **Rust** (stable toolchain)
- **Tauri CLI v2**: `cargo install tauri-cli --version "^2"`
- **Platform-specific dependencies**:
- **Windows**: WebView2 (included in Windows 10/11), Visual Studio Build Tools
- **macOS**: Xcode Command Line Tools
- **Linux**: `libwebkit2gtk-4.1-dev`, `libappindicator3-dev`, `librsvg2-dev`, `libssl-dev`, `build-essential`
### Development
```bash
cd crates/openfang-desktop
cargo tauri dev
```
This launches the app with hot-reload support. The console window is visible in debug builds for tracing output.
### Production Build
```bash
cd crates/openfang-desktop
cargo tauri build
```
This produces platform-specific installers:
- **Windows**: `.msi` and `.exe` (NSIS) installers
- **macOS**: `.dmg` and `.app` bundle
- **Linux**: `.deb`, `.rpm`, and `.AppImage`
The release binary suppresses the console window on Windows via:
```rust
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
```
### Bundle Configuration
From `tauri.conf.json`:
```json
{
"bundle": {
"active": true,
"targets": "all",
"icon": [
"icons/icon.png",
"icons/32x32.png",
"icons/128x128.png",
"icons/128x128@2x.png"
]
}
}
```
The `"targets": "all"` setting generates every available package format for the current platform. Icons are provided at multiple resolutions, plus an `icon.ico` for Windows.
---
## Plugins
| Plugin | Version | Purpose |
|--------|---------|---------|
| `tauri-plugin-notification` | 2 | Native OS notifications for kernel events and update progress |
| `tauri-plugin-shell` | 2 | Shell/process access from the WebView |
| `tauri-plugin-dialog` | 2 | Native file picker for agent/skill import |
| `tauri-plugin-single-instance` | 2 | Prevents multiple instances (desktop only) |
| `tauri-plugin-autostart` | 2 | Launch at OS login (desktop only) |
| `tauri-plugin-updater` | 2 | Signed auto-updates from GitHub Releases (desktop only) |
| `tauri-plugin-global-shortcut` | 2 | Ctrl+Shift+O/N/C shortcuts (desktop only) |
### Capabilities
The default capability set (defined in `capabilities/default.json`) grants:
```json
{
"identifier": "default",
"windows": ["main"],
"permissions": [
"core:default",
"notification:default",
"shell:default",
"dialog:default",
"global-shortcut:allow-register",
"global-shortcut:allow-unregister",
"global-shortcut:allow-is-registered",
"autostart:default",
"updater:default"
]
}
```
Only the `"main"` window receives these permissions.
---
## Mobile Ready
The codebase includes conditional compilation guards for mobile platform support:
- **Entry point**: The `run()` function is annotated with `#[cfg_attr(mobile, tauri::mobile_entry_point)]`, allowing Tauri to use it as the mobile entry point.
- **Desktop-only features**: System tray setup, single-instance enforcement, and hide-to-tray on close are all gated behind `#[cfg(desktop)]` so they compile out on mobile targets.
- **Mobile targets**: iOS and Android builds are structurally supported by the Tauri 2.0 framework, though the kernel and API server would still boot in-process on the device.
---
## File Structure
```
crates/openfang-desktop/
build.rs # tauri_build::build()
Cargo.toml # Crate dependencies and metadata
tauri.conf.json # Tauri app configuration
capabilities/
default.json # Permission grants for the main window
gen/
schemas/ # Auto-generated Tauri schemas
icons/
icon.png # Source icon (327 KB)
icon.ico # Windows icon
32x32.png # Small icon
128x128.png # Standard icon
128x128@2x.png # HiDPI icon
src/
main.rs # Binary entry point (calls lib::run())
lib.rs # Tauri app builder, state types, event listener
commands.rs # IPC command handlers (get_port, get_status, get_agent_count)
server.rs # ServerHandle, kernel boot, embedded axum server
tray.rs # System tray menu and event handlers
```
---
## Environment Variables
| Variable | Effect |
|----------|--------|
| `RUST_LOG` | Controls tracing verbosity. Defaults to `openfang=info,tauri=info` if unset. |
All other OpenFang environment variables (API keys, configuration) apply as normal since the desktop app boots the same kernel as the headless daemon.