Production Deployment

This guide covers everything you need to deploy OpenFang in production, from initial setup to ongoing maintenance.

Pre-Release Checklist

Before deploying to production, ensure these critical steps are complete:

1. Generate Signing Keys (Desktop App Only)

BLOCKING: Without signing keys, the desktop app auto-updater will never receive updates.

Generate an Ed25519 keypair for signing releases:

Install Tauri CLI

cargo install tauri-cli --locked

Generate keypair

cargo tauri signer generate -w ~/.tauri/openfang.key

Save both outputs:

Public key: Copy the printed string (starts with dW50cnVzdGVkIGNvb...)
Private key: Saved to ~/.tauri/openfang.key

Update tauri.conf.json

Replace the pubkey placeholder:

"pubkey": "dW50cnVzdGVkIGNvb..."  // Your actual public key

Add GitHub secrets

Go to Settings → Secrets → Actions and add:

Secret Name	Value
`TAURI_SIGNING_PRIVATE_KEY`	Contents of `~/.tauri/openfang.key`
`TAURI_SIGNING_PRIVATE_KEY_PASSWORD`	Password from keygen (or empty)

2. Verify Docker Build

Ensure the Dockerfile produces a working image:

docker build -t openfang:test .
docker run --rm openfang:test --version
docker run --rm -p 4200:4200 -v test-data:/data openfang:test start

Confirm:

Binary runs and prints version
start command boots the kernel and API server
Port 4200 is accessible
/data volume persists between restarts

3. Set Up Domain (Optional)

For easy installation via curl -sSf https://openfang.sh | sh:

GitHub Pages
Cloudflare Workers
Direct GitHub

Point openfang.sh to a GitHub Pages site that redirects:

/ → scripts/install.sh
/install.ps1 → scripts/install.ps1

Serve install scripts with proper Content-Type: text/plain headers.

Use CNAME to raw.githubusercontent.com/RightNow-AI/openfang/main/scripts/install.sh

Until the domain is ready, users can install via:

curl -sSf https://raw.githubusercontent.com/RightNow-AI/openfang/main/scripts/install.sh | sh

4. Verify Icon Assets

Check that crates/openfang-desktop/icons/ contains real branded icons (not Tauri defaults):

File	Size	Usage
`icon.png`	1024x1024	macOS .icns generation
`icon.ico`	multi-size	Windows taskbar, installer
`32x32.png`	32x32	System tray
`128x128.png`	128x128	Application lists
`[email protected]`	256x256	HiDPI/Retina displays

Daemon Management

systemd Service (Linux)

Create /etc/systemd/system/openfang.service:

[Unit]
Description=OpenFang Agent Operating System
After=network.target

[Service]
Type=simple
User=openfang
Group=openfang
WorkingDirectory=/opt/openfang
EnvironmentFile=/opt/openfang/.env
ExecStart=/usr/local/bin/openfang start
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openfang

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/openfang

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable openfang
sudo systemctl start openfang
sudo systemctl status openfang

Docker Compose (Production)

Add restart policy and health checks:

services:
  openfang:
    image: ghcr.io/rightnow-ai/openfang:latest
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4200/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 4G

Windows Service

Use NSSM to run OpenFang as a Windows service:

nssm install OpenFang "C:\Program Files\OpenFang\openfang.exe" start
nssm set OpenFang AppDirectory "C:\Users\openfang\.openfang"
nssm set OpenFang AppStdout "C:\Users\openfang\.openfang\logs\service.log"
nssm set OpenFang AppStderr "C:\Users\openfang\.openfang\logs\service.log"
nssm start OpenFang

Backup and Recovery

What to Back Up

Configuration

~/.openfang/config.toml
~/.openfang/.env

SQLite databases

~/.openfang/data/openfang.db
~/.openfang/data/*.db

Agent definitions

~/.openfang/agents/

Custom skills

~/.openfang/skills/

Backup Script

#!/bin/bash
BACKUP_DIR="/backups/openfang/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

# Stop the service
sudo systemctl stop openfang

# Copy data
cp -r ~/.openfang/config.toml "$BACKUP_DIR/"
cp -r ~/.openfang/.env "$BACKUP_DIR/"
cp -r ~/.openfang/data/ "$BACKUP_DIR/"
cp -r ~/.openfang/agents/ "$BACKUP_DIR/"
cp -r ~/.openfang/skills/ "$BACKUP_DIR/"

# Restart the service
sudo systemctl start openfang

# Compress
tar -czf "$BACKUP_DIR.tar.gz" -C /backups/openfang "$(basename $BACKUP_DIR)"
rm -rf "$BACKUP_DIR"

echo "Backup saved to: $BACKUP_DIR.tar.gz"

Restore Procedure

# Stop the service
sudo systemctl stop openfang

# Extract backup
tar -xzf /backups/openfang/20260307_120000.tar.gz -C /tmp

# Restore files
cp -r /tmp/20260307_120000/* ~/.openfang/

# Restart the service
sudo systemctl start openfang

Monitoring and Logging

Health Check Endpoint

curl http://localhost:4200/api/health

Response:

{
  "status": "healthy",
  "uptime_secs": 86400,
  "agents": 12
}

Structured Logging

OpenFang uses tracing for structured logs. Configure verbosity:

RUST_LOG=openfang=info,openfang_kernel=debug openfang start

Log levels:

error — Critical failures only
warn — Warnings and errors
info — Normal operations (default)
debug — Verbose debugging
trace — Full trace output

Log Rotation

Configure logrotate for Linux:

/opt/openfang/logs/*.log {
    daily
    rotate 14
    compress
    delaycompress
    notifempty
    missingok
    create 0640 openfang openfang
    postrotate
        systemctl reload openfang
    endscript
}

Prometheus Metrics (Future)

Built-in Prometheus exporter is planned for v0.2.0. Track progress at #metrics.

Planned metrics:

Agent invocation counts
LLM API latency and token usage
Channel adapter message throughput
Memory usage and consolidation events

Performance Tuning

SQLite Optimization

Add to config.toml:

[memory]
sqlite_path = "~/.openfang/data/openfang.db"
consolidation_threshold = 50000  # Increase for large workloads
decay_rate = 0.05  # Lower = slower memory decay

For high-write workloads, enable WAL mode:

sqlite3 ~/.openfang/data/openfang.db 'PRAGMA journal_mode=WAL;'

Resource Limits

Docker Compose:

deploy:
  resources:
    limits:
      cpus: '4'
      memory: 8G
    reservations:
      cpus: '1'
      memory: 2G

systemd:

[Service]
MemoryMax=8G
CPUQuota=400%

Concurrent Agent Limits

Limit simultaneous agent executions in config.toml:

max_concurrent_agents = 10  # Default: unlimited

Upgrading

Version Check

openfang --version

Upgrade Procedure

Backup data

See Backup and Recovery

Stop the service

sudo systemctl stop openfang
# or
docker compose down

Install new version

Binary:

curl -sSf https://openfang.sh | sh

Docker:

docker compose pull
docker compose up -d

Verify upgrade

openfang --version
curl http://localhost:4200/api/health

Breaking Changes

Check CHANGELOG.md for breaking changes between versions. Major version updates may require config migration:

openfang migrate-config --from 0.1.0 --to 0.2.0

Security Hardening

API Authentication

Enable API key authentication in config.toml:

api_key = "your-secure-random-key"

Clients must include the key in requests:

curl -H "Authorization: Bearer your-secure-random-key" \
  http://localhost:4200/api/agents

Network Isolation

Bind only to localhost if not exposing externally:

api_listen = "127.0.0.1:4200"

For external access, use a reverse proxy (nginx, Caddy) with TLS.

Secrets Management

Never commit .env files. Use a secrets manager:

Vault: HashiCorp Vault
AWS: Secrets Manager or Parameter Store
GCP: Secret Manager
Azure: Key Vault

Load secrets at runtime:

export ANTHROPIC_API_KEY=$(vault kv get -field=api_key secret/openfang/anthropic)

Troubleshooting

Service won’t start

# Check logs
sudo journalctl -u openfang -n 50 --no-pager

# Check port conflicts
sudo lsof -i :4200

High memory usage

# Check agent count
curl http://localhost:4200/api/agents | jq 'length'

# Consolidate memory
curl -X POST http://localhost:4200/api/memory/consolidate

Agents not responding

# Check health
curl http://localhost:4200/api/health

# Check specific agent
curl http://localhost:4200/api/agents/{agent_id}

See Troubleshooting Guide for detailed diagnostics.

Post-Release Verification

After tagging a release, verify:

GitHub Release Assets

Confirm presence of:

.msi and .exe (Windows desktop)
.dmg (macOS desktop)
.AppImage and .deb (Linux desktop)
latest.json (auto-updater manifest)
CLI binaries (.tar.gz for 5 targets)

Auto-Updater Manifest

Visit https://github.com/RightNow-AI/openfang/releases/latest/download/latest.jsonVerify:

Valid JSON
Contains signature fields
Version matches tag

Docker Image

docker pull ghcr.io/rightnow-ai/openfang:latest
docker run --rm ghcr.io/rightnow-ai/openfang:latest --version

Desktop Auto-Update Test

Install previous version
Wait 10 seconds
Verify update notification appears
Confirm app restarts to new version

Next Steps

Docker Deployment

Run OpenFang in containers

Desktop App

Install the native desktop application

Get Started

Core Concepts

Autonomous Hands

Configuration

Guides

Security

Deployment

​Pre-Release Checklist

​1. Generate Signing Keys (Desktop App Only)

​2. Verify Docker Build

​3. Set Up Domain (Optional)

​4. Verify Icon Assets

​Daemon Management

​systemd Service (Linux)

​Docker Compose (Production)

​Windows Service

​Backup and Recovery

​What to Back Up

​Backup Script

​Restore Procedure

​Monitoring and Logging

​Health Check Endpoint

​Structured Logging

​Log Rotation

​Prometheus Metrics (Future)

​Performance Tuning

​SQLite Optimization

​Resource Limits

​Concurrent Agent Limits

​Upgrading

​Version Check

​Upgrade Procedure

​Breaking Changes

​Security Hardening

​API Authentication

​Network Isolation

​Secrets Management

​Troubleshooting

​Service won’t start

​High memory usage

​Agents not responding

​Post-Release Verification

​Next Steps

Docker Deployment

Desktop App

Build docs developers (and LLMs) love

Pre-Release Checklist

1. Generate Signing Keys (Desktop App Only)

2. Verify Docker Build

3. Set Up Domain (Optional)

4. Verify Icon Assets

Daemon Management

systemd Service (Linux)

Docker Compose (Production)

Windows Service

Backup and Recovery

What to Back Up

Backup Script

Restore Procedure

Monitoring and Logging

Health Check Endpoint

Structured Logging

Log Rotation

Prometheus Metrics (Future)

Performance Tuning

SQLite Optimization

Resource Limits

Concurrent Agent Limits

Upgrading

Version Check

Upgrade Procedure

Breaking Changes

Security Hardening

API Authentication

Network Isolation

Secrets Management

Troubleshooting

Service won’t start

High memory usage

Agents not responding

Post-Release Verification

Next Steps