WebUI Configuration Guide

🌐 AionUi WebUI Configuration Guide(by Commond Line)

This guide covers how to configure and use AionUi in WebUI mode, enabling browser-based access and remote connections to your local AI assistant.

English | 简体中文

🎯 WebUI Mode Overview

WebUI mode allows you to access AionUi through a browser, supporting any browser, LAN access, cross-network remote access, and server deployment.

---

🎯 Usage Scenarios (Click to Jump)

Select your use case:

• 🌐 Cross-Network Access (Recommended): Step 1 → Step 2 → Step 3 (Tailscale)
• 📱 LAN Access: Step 1 → Step 2 → Step 3 (same network)
• 🏠 Local Use Only: Step 1 → Step 2
• 🖥️ Server Deployment: Step 1 → Step 2 → Step 4

---

📋 Quick Command Reference

💡 Recommended: Prefer using the interface method to start WebUI (see "Quick Start" section below), which is simpler and more intuitive.

If you need to use command line, here are the common commands for starting WebUI on each platform:

Platform	Local Access	Network Access (LAN) ⭐
Windows	AionUi.exe --webui	AionUi.exe --webui --remote
macOS	/Applications/AionUi.app/Contents/MacOS/AionUi --webui	/Applications/AionUi.app/Contents/MacOS/AionUi --webui --remote
Linux	AionUi --webui	AionUi --webui --remote
Android	AionUi --no-sandbox --webui	AionUi --no-sandbox --webui --remote

Tip: If the command is not found, use the full path (see detailed instructions below for each platform). Linux root users and Android need to add the --no-sandbox parameter.

---

---

🚀 Quick Start

Method 1: Start in Interface (Recommended) ⭐

1. Open AionUi Application
2. Go to WebUI Settings: Click "WebUI" option in the left menu
3. Enable WebUI:
   • Turn on the "Enable WebUI" switch
   • For LAN access, also turn on the "Allow LAN Access" switch
4. View Access Address: After successful startup, the interface will display the access address and login information

💡 Tip: Interface operations are simpler and more intuitive. This method is recommended.

Configure Channels (Optional)

In the WebUI settings page, you can also configure Channels to connect AionUi to chat platforms like Telegram, Lark, etc.:

1. In the WebUI Settings page, scroll down to the "Channels" section
2. Add Channel:
   • Click "Add Channel" or the corresponding configuration button
   • Select the platform to connect (e.g., Telegram, Lark, etc.)
   • Follow the prompts to complete the configuration (usually requires providing Bot Token or Webhook URL)
3. Use Channel: After configuration, you can chat with AionUi through the corresponding chat platform

💡 Tip: Channels configuration is optional and mainly used to access AionUi through third-party chat platforms. If you only need browser access, you can skip this step.

---

Method 2: Start via Command Line (Alternative)

If you prefer using command line, you can run the following commands in terminal:

🪟 Windows

Open Command Prompt or PowerShell, and run:

AionUi.exe --webui

For LAN access:

AionUi.exe --webui --remote

If command not found, use full path:

"C:\Program Files\AionUi\AionUi.exe" --webui

🍎 macOS

Open Terminal, and run:

/Applications/AionUi.app/Contents/MacOS/AionUi --webui

For LAN access:

/Applications/AionUi.app/Contents/MacOS/AionUi --webui --remote

🐧 Linux

Desktop Environment (Non-root User):

Local Access:

AionUi --webui

Network Access (LAN):

AionUi --webui --remote

Root User:

If using root user, you need to add --no-sandbox flag:

sudo AionUi --webui --no-sandbox
sudo AionUi --webui --remote --no-sandbox

Alternative Methods:

• Using full path: /usr/bin/AionUi --webui
• Using AppImage: ./AionUi-*.AppImage --webui

---

📱 Android (Termux)

Community Contribution: Special thanks to @Manamama for creating this guide!
Original Tutorial: Running AionUi WebUI on Android via Termux + Proot Ubuntu
Related Issues: #217 - Android Support Discussion

⚠️ Important:

• Electron desktop mode is NOT supported on Android, only WebUI mode works
• Install Termux from F-Droid (Google Play version is outdated)
• Requirements: ~5 GB free storage, Internet connection, Android 7.0+

Step 1: Install Termux and Proot

Open Termux and execute:

pkg update -y
pkg install proot-distro -y
proot-distro install ubuntu
proot-distro login ubuntu

Step 2: Install System Dependencies

apt update
apt install -y wget libgtk-3-0 libnss3 libasound2 libgbm1 libxshmfence1 ca-certificates

Step 3: Download and Install AionUi

wget https://github.com/iOfficeAI/AionUi/releases/download/v1.5.2/AionUi_1.5.2_arm64.deb
apt install -y ./AionUi_*.deb
which AionUi

Step 4: Launch AionUi

• Local Access: AionUi --no-sandbox --webui
• Network Access: AionUi --no-sandbox --webui --remote

💡 Quick Start (from Termux main shell):

proot-distro login ubuntu -- bash -c "AionUi --no-sandbox --webui --remote"

Step 5: Access WebUI

Open http://localhost:25808 in your browser

📋 Additional Information

Expected Warnings (Safe to Ignore):

[WARNING] Could not connect to session bus...
[ERROR] Failed to connect to the bus...
[WARNING] Multiple instances of the app detected...

These errors are related to D-Bus and X server, which are not needed for WebUI mode.

Performance Tips:

• Use lightweight browsers (Chrome or Firefox Focus)
• Close background apps to free RAM
• Use WiFi instead of mobile data
• Keep device charged

Troubleshooting:

• Port in use: Add --port 8080 flag
• Permission denied: Run chmod +x /opt/AionUi/aionui
• Out of memory: Close other apps
• Cannot access: Check if AionUi is running, clear browser cache

Need Help?
Check the full detailed tutorial or report issues at GitHub Issue #217

---

Step 2: Access the Web Interface

After starting with the --webui flag, you'll see output like:

🚀 WebUI started / WebUI 已启动: http://localhost:25808

Simply open this URL in your browser. The application will automatically open your default browser when started.

---

Step 3: First Login

On first launch, you'll see your initial credentials:

========================================
  ✅ Default admin user created!
========================================
  
  Username: admin
  Password: [random-password]
  
  🌐 Access URL: http://localhost:25808
  
========================================

Important: Copy the password immediately - you'll need it to log in!

---

🌐 Cross-Network Remote Access

Use Case: Access from different networks (e.g., office computer accessing home server, or mobile data access)

By configuring cross-network remote access, you can access your AionUi instance from any network environment without configuring routers or public IPs.

💡 Recommended Solution: You can use remote software like Tailscale for cross-network access. After installing Tailscale, log in with the same account on both server and client devices, then access using the virtual IP assigned by Tailscale (typically 100.x.x.x:25808).

---

📖 Detailed Tutorial

For complete configuration steps and troubleshooting, see:

🌐 Remote Internet Access Tutorial →

---

🌍 LAN Access Configuration

Use Case: Access from devices on the same WiFi/LAN (e.g., phone and computer on the same WiFi)

Step 1: Enable LAN Access

Method 1: Enable in Interface (Recommended) ⭐

1. Open AionUi application
2. Go to WebUI Settings page
3. Turn on the "Enable WebUI" switch
4. Turn on the "Allow LAN Access" switch

Method 2: Use Command Line (Alternative)

Add the --remote flag to your startup command:

• Windows: AionUi.exe --webui --remote
• macOS: /Applications/AionUi.app/Contents/MacOS/AionUi --webui --remote
• Linux: AionUi --webui --remote (root users need to add --no-sandbox)
• Android: AionUi --no-sandbox --webui --remote

Step 2: Get Access Address

After starting, AionUi will display the network access address:

🚀 Network access / 网络访问: http://192.168.1.100:25808

💡 Tip: If not displayed, Windows users run ipconfig, macOS/Linux users run ifconfig to check IP address.

Step 3: Access from Other Devices

Open the displayed address in a browser on other devices (phone, tablet, etc.) and log in with your credentials.

⚠️ Note: Only use remote mode on trusted networks.

---

🔐 Authentication Setup

Default Credentials

When AionUi starts in WebUI mode for the first time, a default admin user is automatically created:

• Username: admin
• Password: Randomly generated 12-character password (displayed in console)

Security Features

• Rate Limiting: Login attempts are rate-limited (5 attempts per 15 minutes)
• Password Hashing: Passwords are hashed using bcrypt
• Session Tokens: JWT tokens for secure session management
• Cookie Protection: HttpOnly and SameSite cookies for CSRF protection

User Information

⚠️ Important: WebUI currently supports single user (admin) only. Multi-user functionality is under development.

---

🖥️ Server Deployment

Use Case: Run 24/7 on servers with remote access and auto-restart support

🍎 macOS - LaunchAgent Background Running

Step 1: Create Configuration File

Create ~/Library/LaunchAgents/com.aionui.webui.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.aionui.webui</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Applications/AionUi.app/Contents/MacOS/AionUi</string>
    <string>--webui</string>
    <string>--remote</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

Step 2: Start Service

launchctl load ~/Library/LaunchAgents/com.aionui.webui.plist
launchctl start com.aionui.webui

🐧 Linux - systemd (Recommended)

Step 1: Create Service File

sudo nano /etc/systemd/system/aionui-webui.service

Step 2: Add Configuration

[Unit]
Description=AionUi WebUI Service
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME
ExecStart=/usr/bin/AionUi --webui --remote
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

💡 Tip: Replace YOUR_USERNAME and /usr/bin/AionUi with actual values.

Step 3: Enable and Start

sudo systemctl daemon-reload
sudo systemctl enable aionui-webui.service
sudo systemctl start aionui-webui.service
sudo systemctl status aionui-webui.service

Common Management Commands:

• View logs: sudo journalctl -u aionui-webui.service -f
• Restart service: sudo systemctl restart aionui-webui.service
• Stop service: sudo systemctl stop aionui-webui.service

Step 4: Get Access Address

Check the access address in logs, or run:

sudo journalctl -u aionui-webui.service | grep "WebUI"

💡 Custom Port: Add Environment="AIONUI_PORT=8080" in [Service], then restart the service.

---

🔑 Password Management

Manage Password in Interface (Recommended) ⭐

In the AionUi application interface, you can easily manage WebUI passwords:

1. Open AionUi Application
2. Go to WebUI Settings: Click "WebUI" option in the left menu
3. View Password:
   • On first startup, password is displayed in plaintext and can be copied directly
   • After copying, password automatically hides as ******
4. Reset Password:
   • Click the refresh icon 🔄 next to the password
   • A dialog will pop up to set a new password
   • You can set a custom password or generate a random one
5. Change Password:
   • Enter and confirm the new password in the dialog
   • After successful password change, previous session tokens will be invalidated and you need to log in again

💡 Tip: Interface operations are simpler and more intuitive. This method is recommended.

Reset Password via Command Line (Alternative)

If you prefer using command line, you can also run the --resetpass command in terminal:

Windows

Open Command Prompt or PowerShell, and run:

Reset admin password:

"C:\Program Files\AionUi\AionUi.exe" --resetpass
# Or specify username explicitly
"C:\Program Files\AionUi\AionUi.exe" --resetpass admin

⚠️ Note: Currently only the admin user is supported. The username parameter is reserved for future multi-user functionality.

macOS

Open Terminal, and run:

Reset admin password:

/Applications/AionUi.app/Contents/MacOS/AionUi --resetpass
# Or specify username explicitly
/Applications/AionUi.app/Contents/MacOS/AionUi --resetpass admin

⚠️ Note: Currently only the admin user is supported. The username parameter is reserved for future multi-user functionality.

Linux

Open Terminal, and run:

Reset admin password:

AionUi --resetpass
# Or specify username explicitly
AionUi --resetpass admin

⚠️ Note: Currently only the admin user is supported. The username parameter is reserved for future multi-user functionality.

What happens when you run --resetpass:

1. Connects to the database
2. Finds the specified user (default: admin, can be specified via parameter)
3. Generates a new random 12-character password
4. Updates the password hash in the database
5. Rotates the JWT secret (invalidating all previous tokens)
6. Displays the new password in the terminal

⚠️ Note: Currently only the admin user is supported. The username parameter is reserved for future multi-user functionality.

After running --resetpass:

1. Copy the new password from the terminal
2. Refresh your browser (Cmd+R or Ctrl+R)
3. You'll be redirected to the login page
4. Log in with the new password shown in the terminal

---

🛠️ Troubleshooting

Port Already in Use

If port 25808 is already in use, AionUi will automatically try the next available port. Check the console output for the actual port number.

Cannot Access from Browser

1. Check if the application started successfully

   • Look for "Server started on port XXXX" message in the console

2. Try a different browser

   • Chrome, Firefox, Safari, or Edge

3. Clear browser cache

   • Press Ctrl+Shift+Delete (Windows/Linux) or Cmd+Shift+Delete (macOS)

Firewall Blocking Access

Windows:

# Allow through Windows Firewall
netsh advfirewall firewall add rule name="AionUi WebUI" dir=in action=allow protocol=TCP localport=25808

Linux (UFW):

sudo ufw allow 25808/tcp

macOS:

• Go to System Preferences → Security & Privacy → Firewall → Firewall Options → Add AionUi

Application Not Found

Find application location:

Windows:

where AionUi.exe

macOS:

mdfind -name "AionUi.app"

Linux:

which AionUi
# or
find /usr/bin -name "AionUi" 2>/dev/null

View Logs

Windows (PowerShell):

& "C:\Program Files\AionUi\AionUi.exe" --webui 2>&1 | Tee-Object -FilePath aionui.log

macOS/Linux:

AionUi --webui 2>&1 | tee aionui.log

---

📝 Command Line Options Summary

Option	Description
--webui	Start in WebUI mode
--remote	Allow remote network access
--webui --remote	Combine both flags
--port <port>	Specify port number (default: 25808)
--webui-port <port>	Specify WebUI port (same as --port)
--resetpass [username]	Reset admin password (default: admin, see above)

---

💡 Best Practices

For Development

• Use --webui flag for quick testing
• Enable remote access only on local network
• Keep default admin password secure

For Production

• Use systemd/LaunchAgent for automatic startup
• Set up firewall rules to restrict access
• Use VPN for external access
• Regularly update your password
• Keep AionUi updated to the latest version

For Local Network Access

• Ensure all devices are on the same network
• Check your router settings if access doesn't work
• Use your computer's IP address for access

---

🔗 Related Resources

• 📖 Getting Started Guide - Initial setup and configuration
• ⚙️ LLM Configuration - Configure AI models
• 🤖 Multi-Agent Setup - Integrate terminal AI agents
• 🔌 MCP Configuration - Model Context Protocol setup
• 🌐 Remote Internet Access Tutorial - Configure internet access and HTTPS
• ❓ FAQ - Common issues and solutions

---

🌟 Features

Security

• HTTPS Ready: Can be deployed behind a reverse proxy with SSL
• Session Management: Automatic session timeout after 24 hours
• Rate Limiting: Protection against brute force attacks
• CSRF Protection: Built-in cross-site request forgery protection

Data Storage

• Local SQLite Database: All data stored locally
• No Cloud Storage: Your conversations never leave your computer
• Privacy First: Full control over your data

Performance

• Low Resource Usage: Runs efficiently on most systems
• WebSocket Real-time: Real-time updates via WebSocket
• Efficient Streaming: Optimized response streaming

---

Happy using AionUi in WebUI mode! 🚀