12.7. Headless Mode¶

"Headless Mode" refers to running Backend.AI GO primarily as a background service or server, without relying on the graphical user interface (GUI) for daily interactions. This is particularly useful for setting up a dedicated inference server on a spare machine or managing the application remotely.

Concept¶

Although Backend.AI GO ships as a desktop app, its core runtime is shared:

• Shared Rust runtime: Handles model inference, process orchestration, the Management API, and the Continuum Router.
• Desktop transport: Tauri IPC from the embedded WebView.
• Headless transport: REST and SSE exposed by aigo-server, plus the WebUI served over HTTP.

Headless WebUI and desktop UI therefore execute the same runtime logic; only features that genuinely depend on desktop integration (such as the system tray or native windows) behave differently.

Operation¶

System Tray¶

The simplest form of "headless-like" operation is closing the main window. * By default, closing the window minimizes Backend.AI GO to the System Tray (Menu Bar on macOS). * The API server and model inference continue running in the background.

CLI Control¶

You can use the bundled aigo CLI to manage the application without opening the window.

# List loaded models
aigo model list

# Load a model
aigo model load --name "llama-3-8b-instruct"

# Check system stats
aigo system info

See the CLI Reference for full documentation.

Dedicated Headless Server (aigo-server)¶

Backend.AI GO provides a standalone headless binary:

aigo-server

In this mode:

• The tauri crate is not part of the aigo-server dependency graph.
• The Management API becomes the primary control plane.
• The WebUI connects over HTTP/SSE instead of Tauri IPC.
• Model pools, router management, scheduling, agents, memory, and provider/runtime coordination reuse the same shared runtime managers used by the desktop app.

Remote Access (Server Mode)¶

To turn your local machine into a headless node for others:

1. Go to Settings > Advanced.
2. Enable Remote Access (Allow external connections).
3. Set the API Port (default: 8080).
4. (Optional) Setup a firewall rule to allow traffic on that port.

Now, other instances of Backend.AI GO, the WebUI, or curl/Python scripts can connect to your machine's IP address as if it were a server.

First-Run Sign-in (aigo-server)¶

When aigo-server starts for the first time with no existing data, it serves the Initial Setup screen at http://<host>:8001. Navigate there in a browser, choose a username and password for the admin account, and the server logs you in immediately. No second step is required. Subsequent visits show the Sign in screen.

If the server is bound to a non-local interface, first-run setup also requires a setup token. Managed per-user services should generate a random AIGO_SETUP_TOKEN, start the server with it, and open the user's browser with /#setupToken=<token> so the setup form is prefilled. Operators can also copy the one-time setup token printed in the aigo-server startup log. Localhost-only first-run setup does not require this token.

SDK clients (curl, Python, etc.) use X-API-Key or Authorization: Bearer headers with access keys created from Settings > API Keys after signing in.

Troubleshooting¶

Where API Keys Are Stored¶

In headless mode, Backend.AI GO stores API keys in an encrypted file (encrypted_keys.json) instead of the OS keychain, which requires a GUI. Keys persist across server restarts.

curl http://localhost:8001/api/v1/providers