Desktop Application

The OpenFang Desktop App is a native application built with Tauri 2.0 that packages the entire Agent OS into a single installable application. Run OpenFang with system tray integration, OS notifications, and automatic updates — no CLI required.

Installation

Windows

Download the installer

Download the .msi or .exe installer from GitHub Releases.

Run the installer

Double-click the installer and follow the setup wizard.

Windows SmartScreen may show a warning. Click “More info” → “Run anyway” until code signing is enabled.

Launch OpenFang

The app starts automatically after installation. Find the OpenFang icon in the system tray.

System Requirements:

Windows 10/11
WebView2 (included in Windows 10/11)

macOS

Download the disk image

Download the .dmg file from GitHub Releases.

Install the app

Open the .dmg file
Drag OpenFang.app to the Applications folder
Eject the disk image

First launch

Right-click OpenFang in Applications → Open.

macOS Gatekeeper will block unsigned apps. Click “Open” in the dialog to allow.

System Requirements:

macOS 12.0 (Monterey) or later
Intel or Apple Silicon

Linux

AppImage (Universal)
Debian/Ubuntu (.deb)
RPM (Fedora/RHEL)

# Download AppImage
wget https://github.com/RightNow-AI/openfang/releases/latest/download/openfang.AppImage

# Make executable
chmod +x openfang.AppImage

# Run
./openfang.AppImage

AppImages are self-contained and work on any Linux distribution.

# Download .deb package
wget https://github.com/RightNow-AI/openfang/releases/latest/download/openfang_amd64.deb

# Install
sudo dpkg -i openfang_amd64.deb

# Fix dependencies if needed
sudo apt-get install -f

# Launch
openfang

# Download .rpm package
wget https://github.com/RightNow-AI/openfang/releases/latest/download/openfang.x86_64.rpm

# Install
sudo rpm -i openfang.x86_64.rpm

# Launch
openfang

System Requirements:

Debian 11+, Ubuntu 20.04+, Fedora 35+, or equivalent
libwebkit2gtk-4.1, libappindicator3

Features

System Tray Integration

The system tray provides quick access without opening the main window:

Menu Item	Behavior
Show Window	Opens/focuses the main window
Open in Browser	Opens `http://127.0.0.1:{port}` in default browser
Agents: N running	Info only — shows active agent count
Status: Running (uptime)	Info only — shows uptime
Launch at Login	Toggle OS-level auto-start
Check for Updates…	Manually check for updates
Open Config Directory	Opens `~/.openfang/` in file manager
Quit OpenFang	Exit the application

Tip: Left-click the tray icon to show the main window.

Single Instance Enforcement

OpenFang prevents multiple instances from running simultaneously. If you try to launch a second instance:

The existing instance’s window is shown and focused
The second launch exits immediately
No duplicate processes or port conflicts

This ensures only one kernel and API server is active at a time.

Hide to Tray on Close

Closing the main window does not quit the application — it hides to the tray and continues running in the background. To fully quit:

Right-click the tray icon → Quit OpenFang
Or use Cmd+Q (macOS) / Alt+F4 (Windows/Linux) when the window is focused

Native OS Notifications

The app shows native notifications for critical kernel events:

Event	Notification
Agent crashes	”Agent Crashed” `Agent {id} crashed: {error}`
Agent spawned	”Agent Started” `Agent "{name}" is now running`
Health check failed	”Health Check Failed” `Agent {id} unresponsive for {secs}s`
Update available	”OpenFang Updating…” `Downloading update...`

Notifications respect OS-level Do Not Disturb settings.

Automatic Updates

The desktop app checks for updates automatically:

10 seconds after startup — Silent check, downloads/installs if available
Manual check — Via system tray → “Check for Updates…”

When an update is found:

Download

Update is downloaded in the background. A notification shows progress.

Install

The update is verified using the Ed25519 signature from tauri.conf.json.

Restart

The app automatically restarts to the new version.

Updates are signed and verified — unsigned updates are rejected. Enable auto-start via:

System tray → “Launch at Login”
Settings (if exposed in UI)

How it works:

macOS: Adds to Login Items via launchd
Windows: Adds registry key to HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run
Linux: Creates ~/.config/autostart/openfang.desktop

Architecture

The desktop app runs the full OpenFang kernel in-process:

┌─────────────────────────────────────────┐
│  Tauri 2.0 Process                      │
│                                         │
│  ┌───────────┐    ┌─────────────────┐  │
│  │  WebView  │    │ Background      │  │
│  │  Window   │◄───┤ Thread          │  │
│  │           │    │ "openfang-srv" │  │
│  │  System   │    │                 │  │
│  │  Tray     │    │ tokio runtime   │  │
│  └───────────┘    │ axum API        │  │
│                   │ OpenFang Kernel │  │
│                   └─────────────────┘  │
│        │                   │           │
│        └── http://127.0.0.1:{port} ────┘
└─────────────────────────────────────────┘

Key components:

Main Thread: Runs the Tauri event loop, WebView, system tray
Background Thread: Runs a dedicated tokio runtime with the OpenFang kernel and axum API server
IPC Bridge: Tauri commands connect the WebView to the kernel

Startup Sequence

Tracing initialization

Configured with RUST_LOG, defaults to openfang=info,tauri=info

Kernel boot

OpenFangKernel::boot(None) loads config from ~/.openfang/config.toml

Port binding

Binds to 127.0.0.1:0 (OS-assigned random port) to avoid conflicts

Server thread spawn

Dedicated OS thread named "openfang-server" runs:

kernel.start_background_agents()
run_embedded_server() with axum router

Tauri app launch

WebView window loads http://127.0.0.1:{port} to render the dashboard

Configuration

The desktop app uses the same config file as the CLI:

~/.openfang/config.toml

All configuration options apply. See Configuration Reference.

Environment Variables

Variable	Effect	Default
`RUST_LOG`	Log verbosity	`openfang=info,tauri=info`
`OPENFANG_HOME`	OpenFang home directory	`~/.openfang`
All LLM API keys	Same as CLI	—

Quick Configuration via UI

The desktop app provides a settings interface accessible from the dashboard. Changes are written to config.toml automatically.

IPC Commands

The WebView can call Tauri IPC commands via invoke():

Command	Returns	Description
`get_port`	`u16`	API server port
`get_status`	`{status, port, agents, uptime_secs}`	Runtime status
`get_agent_count`	`usize`	Number of registered agents
`import_agent_toml`	`String`	Opens file picker, imports agent
`import_skill_file`	`String`	Opens file picker, imports skill
`get_autostart`	`bool`	Check if launch-at-login is enabled
`set_autostart`	`()`	Toggle launch-at-login
`check_for_updates`	`{available, version, body}`	Check for updates
`install_update`	Restarts app	Download and install update
`open_config_dir`	`()`	Open `~/.openfang/` in file manager
`open_logs_dir`	`()`	Open `~/.openfang/logs/` in file manager

Example:

import { invoke } from '@tauri-apps/api/core';

const port = await invoke<number>('get_port');
const status = await invoke<{status: string, agents: number}>('get_status');

Global Shortcuts

The desktop app registers global keyboard shortcuts:

Shortcut	Action
Ctrl+Shift+O	Show main window
Ctrl+Shift+N	Create new agent (if UI supports)
Ctrl+Shift+C	Open config directory

Shortcuts work even when the app is in the background.

Building from Source

Prerequisites

Rust: stable toolchain
Tauri CLI v2: cargo install tauri-cli --version "^2"
Platform dependencies:

Windows
macOS
Linux

WebView2 (included in Windows 10/11)
Visual Studio Build Tools

sudo apt install libwebkit2gtk-4.1-dev \
  libappindicator3-dev \
  librsvg2-dev \
  libssl-dev \
  build-essential

Development Build

cd crates/openfang-desktop
cargo tauri dev

This launches the app with:

Hot reload for Rust changes
Console window visible (debug builds)
Unoptimized binary

Production Build

cd crates/openfang-desktop
cargo tauri build

Outputs:

Windows: .msi and .exe in target/release/bundle/
macOS: .dmg and .app in target/release/bundle/
Linux: .deb, .rpm, .AppImage in target/release/bundle/

The release binary:

Suppresses console window (Windows)
Is fully optimized
Includes all assets and dependencies

Plugins

The desktop app uses these Tauri 2.0 plugins:

Plugin	Purpose
`tauri-plugin-notification`	Native OS notifications
`tauri-plugin-shell`	Shell/process access from WebView
`tauri-plugin-dialog`	Native file picker for agent/skill import
`tauri-plugin-single-instance`	Prevent multiple instances (desktop only)
`tauri-plugin-autostart`	Launch at OS login (desktop only)
`tauri-plugin-updater`	Signed auto-updates from GitHub Releases (desktop only)
`tauri-plugin-global-shortcut`	Ctrl+Shift+O/N/C shortcuts (desktop only)

Security

Content Security Policy

The app enforces a strict CSP that only allows connections to the local embedded server:

default-src 'self' http://127.0.0.1:* ws://127.0.0.1:*;
img-src 'self' data: blob: http://127.0.0.1:*;
style-src 'self' 'unsafe-inline';
script-src 'self' 'unsafe-inline' 'unsafe-eval';

This blocks external resource loading while permitting the WebView to communicate with the localhost API.

Update Verification

All updates are signed with an Ed25519 key. The public key is embedded in the app binary:

"pubkey": "dW50cnVzdGVkIGNvb..."

Unsigned or tampered updates are rejected before installation.

Subprocess Sandboxing

Skill execution uses environment isolation — see Security Architecture for details.

Troubleshooting

App won’t start

Windows:

Check Event Viewer → Application logs
Ensure WebView2 is installed

macOS:

Check Console.app for crash logs
Grant permissions in Security & Privacy settings

Linux:

Run from terminal to see errors: ./openfang.AppImage
Check missing dependencies: ldd openfang.AppImage

Update fails

Signature mismatch: Verify pubkey in tauri.conf.json matches the signing key
Network error: Check firewall/proxy settings
Insufficient permissions: Run as administrator (Windows) or grant write access to app bundle (macOS)

High CPU usage

Check the number of running agents:

curl http://localhost:$(cat ~/.openfang/port)/api/agents | jq 'length'

Stop unused agents via the dashboard.

Port already in use

The app binds to a random port (127.0.0.1:0). If startup fails:

Kill existing OpenFang processes
Check for stale lockfiles in ~/.openfang/

Next Steps

Docker Deployment

Run OpenFang in containers

Production Guide

Production deployment checklist

Get Started

Core Concepts

Autonomous Hands

Configuration

Guides

Security

Deployment

​Installation

​Windows

​macOS

​Linux

​Features

​System Tray Integration

​Single Instance Enforcement

​Hide to Tray on Close

​Native OS Notifications

​Automatic Updates

​Launch at Login

​Architecture

​Startup Sequence

​Configuration

​Environment Variables

​Quick Configuration via UI

​IPC Commands

​Global Shortcuts

​Building from Source

​Prerequisites

​Development Build

​Production Build

​Plugins

​Security

​Content Security Policy

​Update Verification

​Subprocess Sandboxing

​Troubleshooting

​App won’t start

​Update fails

​High CPU usage

​Port already in use

​Next Steps

Docker Deployment

Production Guide

Build docs developers (and LLMs) love

Installation

Windows

macOS

Linux

Features

System Tray Integration

Single Instance Enforcement

Hide to Tray on Close

Native OS Notifications

Automatic Updates

Launch at Login

Architecture

Startup Sequence

Configuration

Environment Variables

Quick Configuration via UI

IPC Commands

Global Shortcuts

Building from Source

Prerequisites

Development Build

Production Build

Plugins

Security

Content Security Policy

Update Verification

Subprocess Sandboxing

Troubleshooting

App won’t start

Update fails

High CPU usage

Port already in use

Next Steps