Auto-Discovery¶

Backend.AI GO uses mDNS (Multicast DNS), known as Bonjour on macOS, to announce and discover instances on your local network. A computer that turns on Allow connections without approval (same network) announces itself, and other instances on the same network can find it and connect to it without an IP address or a connection key.

How mDNS Discovery Works¶

mDNS is a zero-configuration protocol that operates over UDP port 5353 using multicast addresses (224.0.0.251 for IPv4, ff02::fb for IPv6). Nodes send announcements to the multicast group, and all other nodes on the same subnet receive them without a central DNS server.

Backend.AI GO registers under the service type _aigo._tcp.local.. Every instance on the network that is browsing for this type will see the announcement.

Advertise and Discover Flow¶

Node A (advertiser)                  Node B (discoverer)
        |                                    |
        |--- mDNS announcement ----------->  |  (UDP 5353 multicast)
        |    _aigo._tcp.local.               |
        |    TXT: name, version,             |
        |         fingerprint, port,         |
        |         engines, models,           |
        |         accelerator                |
        |                                    |
        |                    [Node B sees A] |
        |                                    |
        |<-- Re-announcement every ~20-30s --| (daemon keeps it alive)
        |                                    |
        |--- Graceful departure -----------> | (ServiceRemoved event)
        |    (on shutdown)                   |

Each instance also runs a discovery listener, so the same node can advertise and discover peers simultaneously.

TXT Record Format¶

When advertising, Backend.AI GO includes the following data in mDNS TXT records:

The engines and models fields are omitted when no engines are installed or when the engine manager is unavailable. The accelerator field is omitted when no accelerator is detected.

Capability data updates automatically when:

• An engine is installed or removed (triggered by the engines-changed event).
• The model library changes (triggered by the models-updated event).

Setting Up mDNS Advertising¶

Enable Advertising on This Computer¶

1. Open Settings in Backend.AI GO and select the Nodes tab.
2. Open Share this computer and turn on Share with other computers.
3. Under This computer, enter a Name. Advertising needs one, and other computers list this computer by it.
4. Under Connection methods, turn on Allow connections without approval (same network).

Once enabled, this instance announces itself every 20–30 seconds, and other Backend.AI GO instances on the same subnet see it in their discovery list. Connection methods appears only while Share with other computers is on. Turning sharing off stops the announcements but keeps the switch as you set it, so they resume when sharing is turned back on.

Discover Computers on the Network¶

1. Open Settings > Nodes > Connect other computers. Discovery runs while the page is open and stops when you leave it.
2. Under Add Node, Computers on your network lists the computers found so far and updates as they appear and leave.
3. Click Add Node on a computer in the list. It is added without a connection key, because a computer appears in the list only while it allows connections without approval.

Each computer in the list shows:

• Node name and IP address
• Software version
• Installed inference engines (e.g., llama-cpp, mlx)
• Number of locally available models
• Hardware accelerator type (e.g., metal, cuda, rocm, cpu)

Approval and Connection Keys¶

The Allow connections without approval (same network) switch decides what another computer needs from you to connect. While it is on, any computer on the same network can ask this computer for a connection key through the discovery endpoint and register with that key, and nothing on this computer asks you to approve the connection. The endpoint limits how often it hands out keys but checks nothing else, so turn the switch on only on a network you trust, such as home or office.

The switch applies only while Share with other computers is on. With sharing off, this computer neither announces itself nor hands out keys, whatever the switch is set to.

With the switch off, other computers can still connect, but only with a connection key you create under Connection methods > Connect with a connection key (see Manual Registration). Each key works once and expires after the time chosen in Valid for, from 5 minutes to 1 hour. Computers that connected either way are listed under Computers using this one, where you can remove them; a removed computer has to register again to use this one.

Self-Node Filtering¶

Each node has a unique fingerprint generated at first launch. The discovery service uses this fingerprint to filter out its own mDNS announcement. Your own node never appears in the discovered-nodes list even if it is advertising.

Stale Node Detection¶

If a node shuts down abruptly without sending a departure announcement, the discovery service marks it stale and removes it automatically.

• Staleness threshold: A node is considered stale if it has not been re-announced within 90 seconds. mDNS daemons typically re-announce every 20–30 seconds, so 90 seconds allows three missed announcements before a node is treated as offline.
• Periodic cleanup: Every 30 seconds, the discovery service removes stale entries from the node registry.
• Read-time filtering: get_discovered_nodes() also filters stale nodes on every call, providing a safety net between scheduled cleanups.

When a node comes back online it re-announces and immediately reappears in the peer list.

Troubleshooting Discovery¶

Nodes Not Appearing¶

• Same subnet required: mDNS multicast does not cross router boundaries. Both nodes must be on the same Layer 2 network segment. VLANs or routed subnets will block discovery.
• Firewall rules: Ensure UDP port 5353 is open for multicast traffic on all participating machines. Many operating system firewalls block multicast by default on non-trusted network profiles.
• mDNS advertising not enabled: On the computer you expect to discover, open Settings > Nodes > Share this computer and confirm that both Share with other computers and Allow connections without approval (same network) are on.
• Name not set: The Allow connections without approval (same network) switch stays disabled until the computer has a name under This computer.
• Local Network access off (macOS): The searching computer, or the one being found, does not allow Backend.AI GO on the local network. See Local Network Access on macOS.

Local Network Access on macOS¶

macOS 15 and later ask before an app may reach other computers on the local network. Backend.AI GO checks this permission when you open Settings > Nodes, start discovery, turn on sharing, or add a computer, and macOS shows its alert the first time. While access is off, the Nodes settings show Local Network access is off at the top, and a connection to another computer fails with Host unreachable.

To turn it on, click Open System Settings in that notice, or open System Settings > Privacy & Security > Local Network, and turn on Backend.AI GO. The notice goes away when you return to the app. macOS keeps a refusal across updates and does not ask again, so this switch is the only way to change it. If Backend.AI GO is missing from that list, quit it and open it again: at launch it registers itself with macOS again, and the alert or the list entry appears the next time it reaches the network. A copy started from Terminal is always allowed, which is why a development build never shows the alert.

Nodes Disappearing Unexpectedly¶

• A node vanishes from the peer list if its mDNS announcements are not received within 90 seconds. This can happen when:
• A firewall blocks outgoing multicast packets on the advertising node.
• The node's network interface changes (e.g., switching from Wi-Fi to Ethernet).
• The system enters sleep and the mDNS daemon pauses.

Platform-Specific Notes¶

Network Node Model Discovery After Connection¶

Once two nodes are connected, Backend.AI GO performs a catalog exchange:

1. Handshake: On connection, the network node sends its list of active backends (running models and services).
2. Dynamic updates: When the network node runs or stops a model, your local instance is notified on the next refresh.
3. Model selector: Models on network nodes appear in the chat interface's model selector, grouped by node name.

Local Model Discovery¶

On the local machine, Backend.AI GO also monitors the file system and active processes:

• Folder monitoring: When a model is downloaded to the models/ directory, Backend.AI GO detects the file type (GGUF, safetensors) and determines the appropriate runner (llama.cpp, MLX).
• Process binding: When you run a model, it registers with the local router, which exposes the capability to the frontend UI.