# Understanding the AionUi WebUI Remote Access Mechanism

> Discover the AionUi WebUI remote access mechanism. Learn how AionUi securely opens LAN connections for seamless remote access. Get your network URLs now.

- Repository: [OfficeAI/AionUi](https://github.com/iofficeai/aionui)
- Tags: internals
- Published: 2026-02-15

---

**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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/src/webserver/config/constants.ts) lines 78-84), allowing connections from any network interface.

```typescript
// 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`](https://github.com/iOfficeAI/AionUi/blob/main/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.

```typescript
// 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`](https://github.com/iOfficeAI/AionUi/blob/main/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.

```typescript
// 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.

```typescript
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`](https://github.com/iOfficeAI/AionUi/blob/main/src/webserver/setup.ts)
- **URL display** outputs both local (`localhost`) and network (LAN IP) addresses through `displayInitialCredentials` in [`src/webserver/index.ts`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/src/webserver/setup.ts) to permit these cross-device connections.