feat: add mdns alias publishing

Author: DonPrus

README.md

@@ -33,8 +33,9 @@ Local access chain:
 - `http://nullhub.localhost:19800`
 - `http://127.0.0.1:19800`
 
-`nullhub` prefers the first address that resolves locally and falls back to the
-next one automatically.
+`nullhub` tries to publish `nullhub.local` through `dns-sd`/Bonjour or
+`avahi-publish` when those tools are available, and otherwise falls back to
+`nullhub.localhost` and finally `127.0.0.1`.
 
 ### Runtime Prerequisites
 

src/access.zig

@@ -6,8 +6,15 @@ pub const public_alias_host = "nullhub.local";
 pub const canonical_local_host = "nullhub.localhost";
 pub const fallback_local_host = "127.0.0.1";
 
+pub const Options = struct {
+    public_alias_active: bool = false,
+    public_alias_provider: []const u8 = "none",
+};
+
 pub const AccessUrls = struct {
     local_alias_chain: bool,
+    public_alias_active: bool,
+    public_alias_provider: []const u8,
     direct_url: []const u8,
     browser_open_url: []const u8,
     canonical_url: []const u8,
@@ -34,6 +41,10 @@ pub fn isLocalBindHost(host: []const u8) bool {
 }
 
 pub fn buildAccessUrls(allocator: std.mem.Allocator, host: []const u8, port: u16) !AccessUrls {
+    return buildAccessUrlsWithOptions(allocator, host, port, .{});
+}
+
+pub fn buildAccessUrlsWithOptions(allocator: std.mem.Allocator, host: []const u8, port: u16, options: Options) !AccessUrls {
     if (isLocalBindHost(host)) {
         const public_alias_url = try buildUrl(allocator, public_alias_host, port);
         errdefer allocator.free(public_alias_url);
@@ -44,14 +55,17 @@ pub fn buildAccessUrls(allocator: std.mem.Allocator, host: []const u8, port: u16
         const fallback_url = try buildUrl(allocator, fallback_local_host, port);
         errdefer allocator.free(fallback_url);
 
-        const browser_open_url = try buildUrl(allocator, canonical_local_host, port);
+        const browser_open_host = if (options.public_alias_active) public_alias_host else canonical_local_host;
+        const browser_open_url = try buildUrl(allocator, browser_open_host, port);
         errdefer allocator.free(browser_open_url);
 
         const direct_url = try buildUrl(allocator, fallback_local_host, port);
         errdefer allocator.free(direct_url);
 
         return .{
             .local_alias_chain = true,
+            .public_alias_active = options.public_alias_active,
+            .public_alias_provider = options.public_alias_provider,
             .direct_url = direct_url,
             .browser_open_url = browser_open_url,
             .canonical_url = canonical_url,
@@ -74,6 +88,8 @@ pub fn buildAccessUrls(allocator: std.mem.Allocator, host: []const u8, port: u16
 
     return .{
         .local_alias_chain = false,
+        .public_alias_active = false,
+        .public_alias_provider = "none",
         .direct_url = direct_url,
         .browser_open_url = browser_open_url,
         .canonical_url = canonical_url,
@@ -91,6 +107,8 @@ test "buildAccessUrls uses nullhub local chain for loopback binds" {
     defer urls.deinit(std.testing.allocator);
 
     try std.testing.expect(urls.local_alias_chain);
+    try std.testing.expect(!urls.public_alias_active);
+    try std.testing.expectEqualStrings("none", urls.public_alias_provider);
     try std.testing.expectEqualStrings("http://nullhub.local:19800", urls.public_alias_url.?);
     try std.testing.expectEqualStrings("http://nullhub.localhost:19800", urls.browser_open_url);
     try std.testing.expectEqualStrings("http://nullhub.localhost:19800", urls.canonical_url);
@@ -107,3 +125,15 @@ test "buildAccessUrls keeps direct host for non-local binds" {
     try std.testing.expectEqualStrings("http://192.168.1.50:22000", urls.browser_open_url);
     try std.testing.expectEqualStrings("http://192.168.1.50:22000", urls.direct_url);
 }
+
+test "buildAccessUrls prefers public alias when it is active" {
+    var urls = try buildAccessUrlsWithOptions(std.testing.allocator, "127.0.0.1", default_port, .{
+        .public_alias_active = true,
+        .public_alias_provider = "dns-sd",
+    });
+    defer urls.deinit(std.testing.allocator);
+
+    try std.testing.expect(urls.public_alias_active);
+    try std.testing.expectEqualStrings("dns-sd", urls.public_alias_provider);
+    try std.testing.expectEqualStrings("http://nullhub.local:19800", urls.browser_open_url);
+}

src/api/settings.zig

@@ -6,8 +6,8 @@ const access = @import("../access.zig");
 
 /// GET /api/settings — return hub configuration defaults.
 /// Caller owns the returned memory.
-pub fn handleGetSettings(allocator: std.mem.Allocator, host: []const u8, port: u16) ![]const u8 {
-    var urls = try access.buildAccessUrls(allocator, host, port);
+pub fn handleGetSettings(allocator: std.mem.Allocator, host: []const u8, port: u16, access_options: access.Options) ![]const u8 {
+    var urls = try access.buildAccessUrlsWithOptions(allocator, host, port, access_options);
     defer urls.deinit(allocator);
 
     var buf = std.array_list.Managed(u8).init(allocator);
@@ -105,6 +105,11 @@ fn appendAccessJson(buf: *std.array_list.Managed(u8), urls: access.AccessUrls) !
     try buf.appendSlice(urls.fallback_url);
     try buf.appendSlice("\",\"local_alias_chain\":");
     try buf.appendSlice(if (urls.local_alias_chain) "true" else "false");
+    try buf.appendSlice(",\"public_alias_active\":");
+    try buf.appendSlice(if (urls.public_alias_active) "true" else "false");
+    try buf.appendSlice(",\"public_alias_provider\":\"");
+    try buf.appendSlice(urls.public_alias_provider);
+    try buf.append('"');
     try buf.appendSlice(",\"public_alias_url\":");
     if (urls.public_alias_url) |url| {
         try buf.append('"');
@@ -121,7 +126,7 @@ fn appendAccessJson(buf: *std.array_list.Managed(u8), urls: access.AccessUrls) !
 test "handleGetSettings returns valid JSON with defaults" {
     const allocator = std.testing.allocator;
 
-    const json = try handleGetSettings(allocator, access.default_bind_host, access.default_port);
+    const json = try handleGetSettings(allocator, access.default_bind_host, access.default_port, .{});
     defer allocator.free(json);
 
     const parsed = try std.json.parseFromSlice(
@@ -136,6 +141,8 @@ test "handleGetSettings returns valid JSON with defaults" {
                 canonical_url: []const u8,
                 fallback_url: []const u8,
                 local_alias_chain: bool,
+                public_alias_active: bool,
+                public_alias_provider: []const u8,
                 public_alias_url: ?[]const u8,
             },
         },
@@ -150,6 +157,8 @@ test "handleGetSettings returns valid JSON with defaults" {
     try std.testing.expect(parsed.value.auth_token == null);
     try std.testing.expect(parsed.value.auto_update_check == true);
     try std.testing.expect(parsed.value.access.local_alias_chain);
+    try std.testing.expect(!parsed.value.access.public_alias_active);
+    try std.testing.expectEqualStrings("none", parsed.value.access.public_alias_provider);
     try std.testing.expectEqualStrings("http://nullhub.localhost:19800", parsed.value.access.browser_open_url);
     try std.testing.expectEqualStrings("http://nullhub.local:19800", parsed.value.access.public_alias_url.?);
 }

src/api/status.zig

@@ -63,10 +63,10 @@ fn appendInstanceJson(buf: *std.array_list.Managed(u8), entry: state_mod.Instanc
 // ─── Handlers ────────────────────────────────────────────────────────────────
 
 /// GET /api/status — aggregated dashboard data.
-pub fn handleStatus(allocator: std.mem.Allocator, s: *state_mod.State, manager: *manager_mod.Manager, uptime_seconds: u64, host: []const u8, port: u16) ApiResponse {
+pub fn handleStatus(allocator: std.mem.Allocator, s: *state_mod.State, manager: *manager_mod.Manager, uptime_seconds: u64, host: []const u8, port: u16, access_options: access.Options) ApiResponse {
     var buf = std.array_list.Managed(u8).init(allocator);
 
-    buildStatusJson(&buf, s, manager, uptime_seconds, host, port) catch return .{
+    buildStatusJson(&buf, s, manager, uptime_seconds, host, port, access_options) catch return .{
         .status = "500 Internal Server Error",
         .content_type = "application/json",
         .body = "{\"error\":\"internal error\"}",
@@ -75,8 +75,8 @@ pub fn handleStatus(allocator: std.mem.Allocator, s: *state_mod.State, manager:
     return .{ .status = "200 OK", .content_type = "application/json", .body = buf.items };
 }
 
-fn buildStatusJson(buf: *std.array_list.Managed(u8), s: *state_mod.State, manager: *manager_mod.Manager, uptime_seconds: u64, host: []const u8, port: u16) !void {
-    var urls = try access.buildAccessUrls(buf.allocator, host, port);
+fn buildStatusJson(buf: *std.array_list.Managed(u8), s: *state_mod.State, manager: *manager_mod.Manager, uptime_seconds: u64, host: []const u8, port: u16, access_options: access.Options) !void {
+    var urls = try access.buildAccessUrlsWithOptions(buf.allocator, host, port, access_options);
     defer urls.deinit(buf.allocator);
 
     // Hub info
@@ -100,6 +100,11 @@ fn buildStatusJson(buf: *std.array_list.Managed(u8), s: *state_mod.State, manage
     try buf.appendSlice(urls.fallback_url);
     try buf.appendSlice("\",\"local_alias_chain\":");
     try buf.appendSlice(if (urls.local_alias_chain) "true" else "false");
+    try buf.appendSlice(",\"public_alias_active\":");
+    try buf.appendSlice(if (urls.public_alias_active) "true" else "false");
+    try buf.appendSlice(",\"public_alias_provider\":\"");
+    try buf.appendSlice(urls.public_alias_provider);
+    try buf.append('"');
     try buf.appendSlice(",\"public_alias_url\":");
     if (urls.public_alias_url) |url| {
         try buf.append('"');
@@ -161,7 +166,7 @@ test "handleStatus returns valid JSON with hub version" {
     var mgr = manager_mod.Manager.init(allocator, p);
     defer mgr.deinit();
 
-    const resp = handleStatus(allocator, &s, &mgr, 3600, access.default_bind_host, access.default_port);
+    const resp = handleStatus(allocator, &s, &mgr, 3600, access.default_bind_host, access.default_port, .{});
     defer allocator.free(resp.body);
 
     try std.testing.expectEqualStrings("200 OK", resp.status);
@@ -176,6 +181,8 @@ test "handleStatus returns valid JSON with hub version" {
                 uptime_seconds: u64,
                 access: struct {
                     browser_open_url: []const u8,
+                    public_alias_active: bool,
+                    public_alias_provider: []const u8,
                 },
             },
             instances: std.json.ArrayHashMap(std.json.ArrayHashMap(struct {
@@ -193,6 +200,8 @@ test "handleStatus returns valid JSON with hub version" {
     try std.testing.expectEqualStrings("2026.3.2", parsed.value.hub.version);
     try std.testing.expect(parsed.value.hub.platform.len > 0);
     try std.testing.expectEqual(@as(u64, 3600), parsed.value.hub.uptime_seconds);
+    try std.testing.expect(!parsed.value.hub.access.public_alias_active);
+    try std.testing.expectEqualStrings("none", parsed.value.hub.access.public_alias_provider);
     try std.testing.expectEqualStrings("http://nullhub.localhost:19800", parsed.value.hub.access.browser_open_url);
 }
 
@@ -207,7 +216,7 @@ test "handleStatus includes instances" {
 
     try s.addInstance("nullclaw", "my-agent", .{ .version = "2026.3.1", .auto_start = true });
 
-    const resp = handleStatus(allocator, &s, &mgr, 0, access.default_bind_host, access.default_port);
+    const resp = handleStatus(allocator, &s, &mgr, 0, access.default_bind_host, access.default_port, .{});
     defer allocator.free(resp.body);
 
     try std.testing.expectEqualStrings("200 OK", resp.status);
@@ -252,7 +261,7 @@ test "handleStatus includes launch_mode" {
 
     try s.addInstance("nullclaw", "my-agent", .{ .version = "1.0.0", .launch_mode = "agent" });
 
-    const resp = handleStatus(allocator, &s, &mgr, 0, access.default_bind_host, access.default_port);
+    const resp = handleStatus(allocator, &s, &mgr, 0, access.default_bind_host, access.default_port, .{});
     defer allocator.free(resp.body);
 
     try std.testing.expectEqualStrings("200 OK", resp.status);
@@ -268,7 +277,7 @@ test "handleStatus with empty state returns empty instances" {
     var mgr = manager_mod.Manager.init(allocator, p);
     defer mgr.deinit();
 
-    const resp = handleStatus(allocator, &s, &mgr, 42, access.default_bind_host, access.default_port);
+    const resp = handleStatus(allocator, &s, &mgr, 42, access.default_bind_host, access.default_port, .{});
     defer allocator.free(resp.body);
 
     try std.testing.expectEqualStrings("200 OK", resp.status);

src/main.zig

@@ -6,6 +6,7 @@ const server = root.server;
 const paths_mod = root.paths;
 const manager_mod = root.manager;
 const access = root.access;
+const mdns_mod = root.mdns;
 
 const version = "2026.3.2";
 
@@ -35,13 +36,16 @@ pub fn main() !void {
 
             var srv = try server.Server.init(allocator, opts.host, opts.port, &mgr, &mutex);
             defer srv.deinit();
+            var mdns = try mdns_mod.Publisher.init(allocator, paths, opts.host, opts.port);
+            defer mdns.deinit();
+            srv.setAccessOptions(mdns.accessOptions());
 
             const sup_thread = try std.Thread.spawn(.{}, supervisorLoop, .{ &mgr, &mutex });
             sup_thread.detach();
 
             srv.autoStartAll();
 
-            if (!opts.no_open) openBrowser(allocator, opts.host, opts.port);
+            if (!opts.no_open) openBrowser(allocator, opts.host, opts.port, mdns.accessOptions());
 
             try srv.run();
         },
@@ -99,8 +103,8 @@ fn supervisorLoop(manager: *manager_mod.Manager, mutex: *std.Thread.Mutex) void
     }
 }
 
-fn openBrowser(allocator: std.mem.Allocator, host: []const u8, port: u16) void {
-    var urls = access.buildAccessUrls(allocator, host, port) catch return;
+fn openBrowser(allocator: std.mem.Allocator, host: []const u8, port: u16, access_options: access.Options) void {
+    var urls = access.buildAccessUrlsWithOptions(allocator, host, port, access_options) catch return;
     defer urls.deinit(allocator);
 
     var child = switch (builtin.os.tag) {