Understanding the AionUi WebUI Remote Access Mechanism

AionUi enables remote WebUI access through an opt-in mechanism that binds the HTTP server to all network interfaces, dynamically configures CORS to accept LAN connections, and displays accessible network URLs on startup.

The AionUi WebUI remote access mechanism allows developers to interact with the interface from devices beyond the local machine. Implemented in the iOfficeAI/AionUi repository, this feature coordinates server binding, cross-origin resource sharing, and network discovery to safely expose the application across local area networks.

How the AionUi WebUI Remote Access Mechanism Works

The implementation spans three coordinated components within the webserver module. When the allowRemote flag is set to true, the system reconfigures host binding, CORS policies, and URL display logic to accommodate external connections.

Server-Side Host Binding

The foundation of remote access lies in how the HTTP server binds to network interfaces. In src/webserver/index.ts, the startWebServerWithInstance function checks the allowRemote parameter to determine the host address.

When allowRemote is false (default), the server binds to 127.0.0.1, restricting access to the local machine. When enabled, it retrieves SERVER_CONFIG.REMOTE_HOST (defined as 0.0.0.0 in src/webserver/config/constants.ts lines 78-84), allowing connections from any network interface.

// From src/webserver/index.ts (lines 71-73)
const host = allowRemote ? SERVER_CONFIG.REMOTE_HOST : SERVER_CONFIG.DEFAULT_HOST;
// SERVER_CONFIG.REMOTE_HOST = '0.0.0.0'
// SERVER_CONFIG.DEFAULT_HOST = '127.0.0.1'

Dynamic CORS Configuration

Binding to 0.0.0.0 alone does not guarantee browser access due to same-origin policies. The AionUi WebUI remote access mechanism addresses this through dynamic CORS configuration in src/webserver/setup.ts.

The setupCors function builds an allowed-origins set that always includes local URLs (http://localhost:<port> and http://127.0.0.1:<port>). When allowRemote is enabled, the function detects the machine's LAN IP using os.networkInterfaces() and adds http://<LAN-IP>:<port> to the whitelist.

// From src/webserver/setup.ts (lines 24-30)
if (allowRemote) {
  const lanIP = getLocalIP(); // Uses os.networkInterfaces()
  if (lanIP) {
    baseOrigins.add(`http://${lanIP}:${port}`);
  }
}

Network URL Discovery and Display

To complete the AionUi WebUI remote access mechanism, the system provides users with the correct network address. In src/webserver/index.ts, the displayInitialCredentials helper (lines 90-103) executes after the server starts listening.

This function retrieves the server IP using getServerIP() (which scans network interfaces), then constructs both local and network URLs. The console output clearly distinguishes between local access (http://localhost:<port>) and network access (http://<LAN-IP>:<port>), enabling users to copy the appropriate address for remote devices.

// Console output format from src/webserver/index.ts (lines 75-78)
console.log(`🚀 Local access / 本地访问: http://localhost:${port}`);
if (serverIP) {
  console.log(`🚀 Network access / 网络访问: http://${serverIP}:${port}`);
}

Enabling Remote Access in AionUi

Activating the AionUi WebUI remote access mechanism requires passing the allowRemote parameter when starting the server. Set this boolean flag to true in the startWebServer function call.

import { startWebServer } from '@/webserver';

// Start on port 25808 with remote access enabled
await startWebServer(25808, true);

When executed, the server initializes with the following characteristics:

• Binds to 0.0.0.0 accepting external connections
• Configures CORS to allow the detected LAN IP
• Outputs both local and network URLs to the console

Security Considerations

The AionUi WebUI remote access mechanism operates as an opt-in feature to minimize security exposure. When disabled (default), the server remains inaccessible from external networks, reducing the attack surface.

When enabled, the system maintains security through:

• CSRF protection middleware that validates request origins
• Security headers applied to all responses
• Rate limiting to prevent brute-force attacks against authentication endpoints

The CORS configuration specifically restricts access to the detected LAN IP rather than using wildcard (*) origins, ensuring only devices on the same local network can connect, not arbitrary internet hosts.

Summary

The AionUi WebUI remote access mechanism provides a secure, opt-in method for accessing the interface across local networks:

• Host binding switches from 127.0.0.1 to 0.0.0.0 via SERVER_CONFIG.REMOTE_HOST when allowRemote is enabled
• Dynamic CORS automatically detects the LAN IP using os.networkInterfaces() and adds it to the allowed origins set in src/webserver/setup.ts
• URL display outputs both local (localhost) and network (LAN IP) addresses through displayInitialCredentials in src/webserver/index.ts
• Security remains enforced through CSRF protection, security headers, and rate limiting even when remote access is active

Frequently Asked Questions

How do I enable remote access for AionUi WebUI?

Pass true as the second argument to the startWebServer function. For example: await startWebServer(25808, true). This activates the remote access mechanism, binding the server to 0.0.0.0 and configuring CORS for your LAN IP.

What IP address does AionUi bind to when remote access is disabled?

When remote access is disabled (the default), AionUi binds to 127.0.0.1 (localhost) only. This value is defined as SERVER_CONFIG.DEFAULT_HOST in src/webserver/config/constants.ts, ensuring the server rejects external network connections.

Is AionUi WebUI remote access secure for production use?

Remote access in AionUi is designed for local network usage, not public internet exposure. While the mechanism includes CSRF protection, security headers, and rate limiting, it binds to 0.0.0.0 without authentication barriers beyond the application login. For production environments, deploy behind a reverse proxy with HTTPS and additional access controls.

Why does AionUi need to detect my LAN IP for CORS?

Browsers enforce the Same-Origin Policy, blocking requests from different origins unless explicitly allowed. When you access AionUi from another device on your network (e.g., http://192.168.1.42:25808), the browser sends that origin in the request. AionUi detects your LAN IP via os.networkInterfaces() and adds it to the CORS whitelist in src/webserver/setup.ts to permit these cross-device connections.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}