docs/guides/webui.md
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.
WebUI mode starts AionUi with an embedded web server, allowing you to:
--remote flag)Default access URL: http://localhost:3000 (port may vary, check the application output)
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
"C:\Program Files\AionUi\AionUi.exe" --webui
Create start-aionui-webui.bat:
@echo off
"C:\Program Files\AionUi\AionUi.exe" --webui
pause
Double-click the batch file to start WebUI mode.
Open Terminal and run:
# Using full path
/Applications/AionUi.app/Contents/MacOS/AionUi --webui
# Or using open command
open -a AionUi --args --webui
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
/Applications/AionUi.app/Contents/MacOS/AionUi --webui
# Using system path
aionui --webui
# Or using full path
/opt/AionUi/aionui --webui
# Make AppImage executable (first time only)
chmod +x AionUi-*.AppImage
# Run with --webui flag
./AionUi-*.AppImage --webui
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.
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
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
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
# Update package list
pkg update -y
# Install proot-distro
pkg install proot-distro -y
# Install Ubuntu rootfs
proot-distro install ubuntu
# Login to Ubuntu environment
proot-distro login ubuntu
# 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
# 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
# Start AionUi in WebUI mode with no-sandbox flag
AionUi --no-sandbox --webui
Important: The --no-sandbox flag is required in Termux/proot environments.
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.
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.
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
If port 25808 is occupied:
# Specify a different port
AionUi --no-sandbox --webui --port 8080
# Ensure the binary has execute permissions
chmod +x /opt/AionUi/aionui
AionUi requires sufficient RAM. Close other apps if you encounter memory issues.
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
From Termux main shell:
proot-distro login ubuntu -- bash -c "AionUi --no-sandbox --webui --remote"
If you encounter issues or have suggestions for improving Android support:
To allow access from other devices on your network, use the --remote flag:
AionUi.exe --webui --remote
/Applications/AionUi.app/Contents/MacOS/AionUi --webui --remote
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.
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
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.
Check if the application started successfully
Try a different browser
Clear browser cache
Ctrl+Shift+Delete (Windows/Linux) or Cmd+Shift+Delete (macOS)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
Find application location:
Windows:
where AionUi.exe
macOS:
mdfind -name "AionUi.app"
Linux:
which aionui
# or
find /opt -name "aionui" 2>/dev/null
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
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
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.
| Option | Description |
|---|---|
--webui | Start in WebUI mode |
--remote | Allow remote network access |
--webui --remote | Combine both flags |
If you forgot your admin password in WebUI mode, you can reset it using the --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
admin)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
If you encounter any issues:
Happy using AionUi in WebUI mode! 🚀