iofficeai--aionui/docs/guides/webui.md

AionUi WebUI Mode - Startup Guide

AionUi supports WebUI mode, allowing you to access the application through a web browser. This guide covers how to start WebUI mode on all supported platforms.

Table of Contents

• What is WebUI Mode?
• Windows
• macOS
• Linux
• Android (Termux)
• Remote Access
• Troubleshooting

---

What is WebUI Mode?

WebUI mode starts AionUi with an embedded web server, allowing you to:

• Access the application through any modern web browser
• Use AionUi from remote devices on the same network (with --remote flag)
• Run the application headless on servers

Default access URL: http://localhost:3000 (port may vary, check the application output)

---

Windows

Method 1: Command Line (Recommended)

Open Command Prompt or PowerShell and run:

# Using full path
"C:\Program Files\AionUi\AionUi.exe" --webui

# Or if AionUi is in your PATH
AionUi.exe --webui

Method 2: Create a Desktop Shortcut

1. Right-click on desktop → New → Shortcut
2. Enter target location:

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

3. Name it AionUi WebUI
4. Click Finish
5. Double-click the shortcut to launch

Method 3: Create a Batch File

Create start-aionui-webui.bat:

@echo off
"C:\Program Files\AionUi\AionUi.exe" --webui
pause

Double-click the batch file to start WebUI mode.

---

macOS

Method 1: Terminal Command (Recommended)

Open Terminal and run:

# Using full path
/Applications/AionUi.app/Contents/MacOS/AionUi --webui

# Or using open command
open -a AionUi --args --webui

Method 2: Create Shell Script

Create start-aionui-webui.sh:

#!/bin/bash
/Applications/AionUi.app/Contents/MacOS/AionUi --webui

Make it executable and run:

chmod +x start-aionui-webui.sh
./start-aionui-webui.sh

Method 3: Create Automator Application

1. Open Automator
2. Choose Application
3. Add Run Shell Script action
4. Enter:

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

5. Save as AionUi WebUI.app
6. Double-click to launch

Method 4: Add to Dock

1. Create an Automator app (Method 3)
2. Drag AionUi WebUI.app to your Dock
3. Click the Dock icon to start WebUI mode anytime

---

Linux

Method 1: Command Line (Recommended)

For .deb Installation

# Using system path
aionui --webui

# Or using full path
/opt/AionUi/aionui --webui

For AppImage

# Make AppImage executable (first time only)
chmod +x AionUi-*.AppImage

# Run with --webui flag
./AionUi-*.AppImage --webui

Method 2: Create Desktop Entry

Create ~/.local/share/applications/aionui-webui.desktop:

[Desktop Entry]
Name=AionUi WebUI
Comment=Start AionUi in WebUI mode
Exec=/opt/AionUi/aionui --webui
Icon=aionui
Terminal=false
Type=Application
Categories=Utility;Office;

Make it executable:

chmod +x ~/.local/share/applications/aionui-webui.desktop

The launcher will appear in your application menu.

Method 3: Create Shell Script

Create ~/bin/start-aionui-webui.sh:

#!/bin/bash
/opt/AionUi/aionui --webui

Make it executable:

chmod +x ~/bin/start-aionui-webui.sh

Run it:

start-aionui-webui.sh

Method 4: Systemd Service (Background)

Create /etc/systemd/system/aionui-webui.service:

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

[Service]
Type=simple
User=YOUR_USERNAME
ExecStart=/opt/AionUi/aionui --webui --remote
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

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

# Check status
sudo systemctl status aionui-webui.service

---

Android (Termux)

Important Note: Electron desktop mode is not supported on Android. However, you can run AionUi in WebUI mode using Termux with a prooted Linux environment.

Community Contribution: This guide is contributed by @Manamama. Special thanks for making AionUi accessible on Android devices! 🙏

Original Tutorial: Running AionUi WebUI on Android via Termux + Proot Ubuntu

Related Issues: #217 - Android Support Discussion

Prerequisites

• Termux from F-Droid (Google Play version is outdated and not recommended)
• ~5 GB free storage
• Internet connection
• Android 7.0+ (tested on Android 14)

Installation Steps

1. Install Termux and Update Packages

# Update package list
pkg update -y

# Install proot-distro
pkg install proot-distro -y

2. Install Ubuntu via Proot

# Install Ubuntu rootfs
proot-distro install ubuntu

# Login to Ubuntu environment
proot-distro login ubuntu

3. Install System Dependencies

# Update Ubuntu package list
apt update

# Install required dependencies
apt install -y \
    wget \
    libgtk-3-0 \
    libnss3 \
    libasound2 \
    libgbm1 \
    libxshmfence1 \
    ca-certificates

# Optional: Install additional libraries if needed
apt install -y \
    libx11-xcb1 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    libatk1.0-0 \
    libcups2

4. Download and Install AionUi

# Download the ARM64 .deb package (replace VERSION with the actual version)
# Check latest version at: https://github.com/iOfficeAI/AionUi/releases
wget https://github.com/iOfficeAI/AionUi/releases/download/vVERSION/AionUi_VERSION_arm64.deb

# Example (replace VERSION with the release tag, e.g. v1.5.2):
wget https://github.com/iOfficeAI/AionUi/releases/download/vVERSION/AionUi_VERSION_arm64.deb

# Install the package
apt install -y ./AionUi_*.deb

# Verify installation
which AionUi

5. Launch AionUi WebUI

# Start AionUi in WebUI mode with no-sandbox flag
AionUi --no-sandbox --webui

Important: The --no-sandbox flag is required in Termux/proot environments.

6. Access the WebUI

Once started, open your browser and navigate to:

http://localhost:25808

Note: The default port is 25808. Check the terminal output if a different port is used.

Expected Warnings (Non-Fatal)

You may see the following warnings in the terminal - these are normal and can be ignored:

[WARNING] Could not connect to session bus: Using X11 for dbus-daemon autolaunch was disabled at compile time
[ERROR] Failed to connect to the bus: Failed to connect to socket: No such file or directory
[WARNING] Multiple instances of the app detected, but not running on display server

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

Remote Access on LAN

To access AionUi from other devices on your local network:

# Start with --remote flag
AionUi --no-sandbox --webui --remote

# Find your Android device's IP address
# In Termux (outside proot):
# ifconfig or ip addr show

Access from other devices: http://YOUR_ANDROID_IP:25808

Troubleshooting

Port Already in Use

If port 25808 is occupied:

# Specify a different port
AionUi --no-sandbox --webui --port 8080

Permission Denied Errors

# Ensure the binary has execute permissions
chmod +x /opt/AionUi/aionui

Out of Memory

AionUi requires sufficient RAM. Close other apps if you encounter memory issues.

Cannot Access from Browser

1. Check if AionUi is running: look for "Server started" message
2. Try using Termux's built-in browser or Chrome
3. Clear browser cache

Performance Tips

1. Use a lightweight browser - Chrome or Firefox Focus recommended
2. Close background apps - Free up RAM for better performance
3. Use WiFi - More stable than mobile data for remote access
4. Keep device charged - Running AionUi consumes battery

Tested Environment

• Device: Android 14
• Termux Version: 0.118.0
• AionUi Version: Latest release (e.g. 1.5.2)
• Proot-distro: Ubuntu (latest)

Creating a Startup Script

For convenience, create a script to launch AionUi quickly:

# Create script in Ubuntu (proot)
cat > ~/start-aionui.sh << 'EOF'
#!/bin/bash
echo "Starting AionUi WebUI..."
AionUi --no-sandbox --webui --remote
EOF

# Make executable
chmod +x ~/start-aionui.sh

# Run anytime
./start-aionui.sh

Quick Start Command (One-liner)

From Termux main shell:

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

Feedback and Improvements

If you encounter issues or have suggestions for improving Android support:

1. Check the original community guide
2. Report issues at GitHub Issues #217
3. Share your experience to help other Android users!

---

Remote Access

To allow access from other devices on your network, use the --remote flag:

Windows

AionUi.exe --webui --remote

macOS

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

Linux

aionui --webui --remote

Security Note: Remote mode allows network access. Use only on trusted networks. Consider setting up authentication and firewall rules for production use.

Finding Your Local IP Address

Windows:

ipconfig

Look for "IPv4 Address" under your active network adapter.

macOS/Linux:

ifconfig
# or
ip addr show

Look for inet address (e.g., 192.168.1.100).

Access from other devices: http://YOUR_IP_ADDRESS:3000

---

Troubleshooting

Port Already in Use

If port 3000 is already in use, the application 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=3000

Linux (UFW):

sudo ufw allow 3000/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 /opt -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:

/path/to/aionui --webui 2>&1 | tee aionui.log

---

Environment Variables

You can customize WebUI behavior with environment variables:

# Override the listening port
export AIONUI_PORT=8080

# Allow remote access without passing --remote
export AIONUI_ALLOW_REMOTE=true

# Optional host hint (0.0.0.0 behaves the same as AIONUI_ALLOW_REMOTE=true)
export AIONUI_HOST=0.0.0.0

# Then start the application
aionui --webui

# You can also pass the port directly via CLI
aionui --webui --port 8080

---

User Configuration File

From v1.5.0+, you can store persistent WebUI preferences in webui.config.json located in your Electron user-data folder:

Platform	Location
Windows	%APPDATA%/AionUi/webui.config.json
macOS	~/Library/Application Support/AionUi/webui.config.json
Linux	~/.config/AionUi/webui.config.json

Example file:

{
  "port": 8080,
  "allowRemote": true
}

Settings from CLI flags take priority, followed by environment variables, then the user config file.

---

Command Line Options Summary

Option	Description
--webui	Start in WebUI mode
--remote	Allow remote network access
--webui --remote	Combine both flags

---

Reset Admin Password

If you forgot your admin password in WebUI mode, you can reset it using the --resetpass command.

Using --resetpass Command

IMPORTANT: The --resetpass command resets the password and generates a new random one. All existing JWT tokens will be invalidated.

Windows:

# Using full path
"C:\Program Files\AionUi\AionUi.exe" --resetpass

# Or for a specific user
"C:\Program Files\AionUi\AionUi.exe" --resetpass username

macOS:

# Using full path
/Applications/AionUi.app/Contents/MacOS/AionUi --resetpass

# Or for a specific user
/Applications/AionUi.app/Contents/MacOS/AionUi --resetpass username

Linux:

# Using system path
aionui --resetpass

# Or for a specific user
aionui --resetpass username

# Or using full path
/opt/AionUi/aionui --resetpass

What happens when you run --resetpass:

1. The command connects to the database
2. Finds the specified user (default: admin)
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

After running --resetpass:

1. The command will display your new password - copy it immediately
2. Refresh your browser (Cmd+R or Ctrl+R)
3. You will be redirected to the login page
4. Login with the new password shown in the terminal

Development Environment Only

If you're in a development environment with Node.js, you can also use:

# In the project directory
npm run resetpass

# Or for a specific user
npm run resetpass -- username

---

Additional Resources

• Main README
• 中文说明
• 日本語ドキュメント
• GitHub Issues

---

Support

If you encounter any issues:

1. Check the Troubleshooting section
2. Search existing issues
3. Create a new issue with:
   • Your OS and version
   • AionUi version
   • Steps to reproduce
   • Error messages or logs

---

Happy using AionUi in WebUI mode! 🚀