@decentnetwork/lan 0.1.18 → 0.1.22

package/dist/cli/commands.d.ts

@@ -265,3 +265,34 @@ export declare function cmdDoraAutofriend(args: {
     values?: string[];
     configDir?: string;
 }): Promise<void>;
+/**
+ * Install the daemon as a persistent system service.
+ *
+ * Linux  → writes /etc/systemd/system/agentnet.service, daemon-reload,
+ *          enable+start. Sets ExecStart to the resolved `agentnet`
+ *          binary and threads --config-dir so sudo's $HOME=/root
+ *          doesn't pick up an empty /root/.agentnet.
+ * macOS  → writes /Library/LaunchDaemons/com.decentlan.agentnet.plist,
+ *          launchctl load (RunAtLoad + KeepAlive).
+ *
+ * Both surfaces stream stdout/stderr to /var/log/agentnet.log so a
+ * single `tail -f /var/log/agentnet.log` works regardless of platform.
+ * `--uninstall` reverses each respectively.
+ *
+ * Requires root (writes to /etc or /Library). On Linux the resolved
+ * unit will run as User=root; on macOS the LaunchDaemon already runs
+ * as root. The CLI complains loudly with the missing-sudo hint if
+ * the writes fail with EACCES.
+ */
+export declare function cmdServiceInstall(args: {
+    uninstall?: boolean;
+    configDir?: string;
+}): Promise<void>;
+/**
+ * Show whether the service is installed + running. Cross-platform
+ * pass-through to systemctl status / launchctl list with a one-line
+ * up/down summary up top.
+ */
+export declare function cmdServiceStatus(_args: {
+    configDir?: string;
+}): Promise<void>;

package/dist/cli/commands.js

@@ -4,7 +4,7 @@
 import { resolve, dirname } from "path";
 import { existsSync, mkdirSync, readFileSync } from "fs";
 import { createConnection } from "net";
-import { ConfigLoader } from "../config/loader.js";
+import { ConfigLoader, DEFAULT_DORA_USERID, DEFAULT_DORA_ADDRESS } from "../config/loader.js";
 import { ipcSocketPath } from "../daemon/ipc.js";
 import { DaemonServer } from "../daemon/server.js";
 import { Ipam } from "../ipam/ipam.js";
@@ -129,7 +129,31 @@ export async function cmdInit(args) {
     console.log(`  Config dir: ${dir}`);
     console.log(`  Subnet: ${config.network.subnet}`);
     console.log(`  Interface: ${config.network.interface}`);
-    console.log(`\nNext: agentnet up --name ${nodeName}`);
+    // Send the one-time friend-request to the default dora so the daemon
+    // can register on first start. Best-effort: a friend-request requires
+    // joinNetwork + an announce round, ~10-30s; we cap the wait and
+    // surface a hint if it doesn't go through. Skipped when the user
+    // overrode dora.userids away from the default (i.e. they're pointing
+    // at a private dora — they'll run `agentnet dora enable` themselves).
+    const defaultDoraConfigured = (config.dora?.userids ?? []).includes(DEFAULT_DORA_USERID);
+    if (defaultDoraConfigured) {
+        console.log(`\nFriending the public dora (${DEFAULT_DORA_USERID.slice(0, 16)}...) so the daemon can join the shared network on first start.`);
+        try {
+            await cmdFriendRequest({
+                address: DEFAULT_DORA_ADDRESS,
+                hello: `decentlan init (${nodeName})`,
+                waitMs: 8000,
+                configDir: dir,
+            });
+            console.log(`  Friend-request dispatched. Auto-accept on the dora side will take it from here.`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`  Friend-request to the default dora failed: ${msg}`);
+            console.warn(`  Re-run later: agentnet dora enable --address ${DEFAULT_DORA_ADDRESS}`);
+        }
+    }
+    console.log(`\nNext: sudo agentnet service install   # or 'agentnet up --real-tun' to run in foreground`);
 }
 /**
  * Show identity information.
@@ -787,7 +811,36 @@ export async function cmdProxyAllowHost(args) {
     config.proxy = { ...proxy, allowHosts: [...allowHosts] };
     await ConfigLoader.save(config, configPath);
     console.log(`Added '${args.host}' to proxy allow-hosts.`);
-    console.log(`Restart the daemon to take effect.`);
+    await applyProxyReloadIfRunning(config);
+}
+/**
+ * If the daemon is up, push the freshly-saved proxy allowlist into the
+ * running proxy over IPC — no restart, no Carrier-session churn. Prints
+ * the outcome. When the daemon is down (or the proxy isn't running yet),
+ * tells the operator a restart is needed.
+ */
+async function applyProxyReloadIfRunning(config) {
+    if (daemonPid(config) === null) {
+        console.log("Daemon is down — change takes effect on next 'agentnet up'.");
+        return;
+    }
+    try {
+        const res = await ipcCall(config, { op: "proxy-reload" });
+        if (!res.ok) {
+            console.log(`(live reload failed: ${res.error}) — restart the daemon to apply.`);
+            return;
+        }
+        const data = res.data;
+        if (data.applied) {
+            console.log(`Applied live to the running proxy — no restart needed.`);
+        }
+        else {
+            console.log(`Not applied live: ${data.reason ?? "proxy not running"}.`);
+        }
+    }
+    catch (err) {
+        console.log(`(live reload error: ${err instanceof Error ? err.message : err}) — restart to apply.`);
+    }
 }
 /**
  * Remove a host glob from the proxy allowlist.
@@ -803,6 +856,7 @@ export async function cmdProxyRevokeHost(args) {
     await ConfigLoader.save(config, configPath);
     if (filtered.length < before) {
         console.log(`Removed '${args.host}' from proxy allow-hosts.`);
+        await applyProxyReloadIfRunning(config);
     }
     else {
         console.log(`No exact match for '${args.host}' in allow-hosts.`);
@@ -1208,3 +1262,169 @@ export async function cmdDoraAutofriend(args) {
     }
     console.log(`Takes effect on the next roster refresh (~60s) or daemon restart.`);
 }
+/**
+ * Install the daemon as a persistent system service.
+ *
+ * Linux  → writes /etc/systemd/system/agentnet.service, daemon-reload,
+ *          enable+start. Sets ExecStart to the resolved `agentnet`
+ *          binary and threads --config-dir so sudo's $HOME=/root
+ *          doesn't pick up an empty /root/.agentnet.
+ * macOS  → writes /Library/LaunchDaemons/com.decentlan.agentnet.plist,
+ *          launchctl load (RunAtLoad + KeepAlive).
+ *
+ * Both surfaces stream stdout/stderr to /var/log/agentnet.log so a
+ * single `tail -f /var/log/agentnet.log` works regardless of platform.
+ * `--uninstall` reverses each respectively.
+ *
+ * Requires root (writes to /etc or /Library). On Linux the resolved
+ * unit will run as User=root; on macOS the LaunchDaemon already runs
+ * as root. The CLI complains loudly with the missing-sudo hint if
+ * the writes fail with EACCES.
+ */
+export async function cmdServiceInstall(args) {
+    const dir = args.configDir || ConfigLoader.defaultConfigDir();
+    const { spawnSync, execSync } = await import("child_process");
+    if (process.platform === "linux") {
+        const unitPath = "/etc/systemd/system/agentnet.service";
+        if (args.uninstall) {
+            spawnSync("systemctl", ["disable", "--now", "agentnet"], { stdio: "inherit" });
+            try {
+                const { unlinkSync, existsSync } = await import("fs");
+                if (existsSync(unitPath))
+                    unlinkSync(unitPath);
+                execSync("systemctl daemon-reload");
+                console.log(`Removed ${unitPath} and disabled the service.`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`Could not remove ${unitPath} (need root?): ${msg}`);
+            }
+            return;
+        }
+        // Resolve the `agentnet` binary. argv[1] is dist/cli/index.js when
+        // invoked as `node …/index.js`, so a `which` lookup is more
+        // portable. Fall back to /usr/local/bin/agentnet (npm-default
+        // global prefix on most Linux setups) if the lookup fails.
+        let agentnetBin;
+        try {
+            agentnetBin = execSync("command -v agentnet", { encoding: "utf-8" }).trim();
+            if (!agentnetBin)
+                throw new Error("not found");
+        }
+        catch {
+            agentnetBin = "/usr/local/bin/agentnet";
+        }
+        const unit = `[Unit]
+Description=Decent AgentNet daemon
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=root
+ExecStart=${agentnetBin} up --real-tun --config-dir ${dir}
+Restart=on-failure
+RestartSec=5
+StandardOutput=append:/var/log/agentnet.log
+StandardError=append:/var/log/agentnet.log
+
+[Install]
+WantedBy=multi-user.target
+`;
+        try {
+            const fs = await import("fs/promises");
+            await fs.writeFile(unitPath, unit, "utf-8");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Could not write ${unitPath} (need root? try 'sudo'): ${msg}`);
+        }
+        execSync("systemctl daemon-reload");
+        execSync("systemctl enable --now agentnet");
+        console.log(`Installed ${unitPath} and started agentnet.service.`);
+        console.log(`Logs: journalctl -u agentnet -f   (or /var/log/agentnet.log)`);
+        return;
+    }
+    if (process.platform === "darwin") {
+        const plistPath = "/Library/LaunchDaemons/com.decentlan.agentnet.plist";
+        if (args.uninstall) {
+            spawnSync("launchctl", ["unload", plistPath], { stdio: "inherit" });
+            try {
+                const { unlinkSync, existsSync } = await import("fs");
+                if (existsSync(plistPath))
+                    unlinkSync(plistPath);
+                console.log(`Unloaded and removed ${plistPath}.`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`Could not remove ${plistPath} (need root?): ${msg}`);
+            }
+            return;
+        }
+        let agentnetBin;
+        try {
+            agentnetBin = execSync("command -v agentnet", { encoding: "utf-8" }).trim();
+            if (!agentnetBin)
+                throw new Error("not found");
+        }
+        catch {
+            agentnetBin = "/usr/local/bin/agentnet";
+        }
+        const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>com.decentlan.agentnet</string>
+  <key>UserName</key><string>root</string>
+  <key>ProgramArguments</key><array>
+    <string>${agentnetBin}</string>
+    <string>up</string>
+    <string>--real-tun</string>
+    <string>--config-dir</string>
+    <string>${dir}</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>/var/log/agentnet.log</string>
+  <key>StandardErrorPath</key><string>/var/log/agentnet.log</string>
+</dict></plist>
+`;
+        try {
+            const fs = await import("fs/promises");
+            await fs.writeFile(plistPath, plist, "utf-8");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Could not write ${plistPath} (need root? try 'sudo'): ${msg}`);
+        }
+        execSync(`launchctl load ${plistPath}`);
+        console.log(`Installed ${plistPath} and started com.decentlan.agentnet.`);
+        console.log(`Logs: tail -f /var/log/agentnet.log`);
+        return;
+    }
+    throw new Error(`'service install' isn't wired up for ${process.platform}. Run 'agentnet up --real-tun' in the foreground for now.`);
+}
+/**
+ * Show whether the service is installed + running. Cross-platform
+ * pass-through to systemctl status / launchctl list with a one-line
+ * up/down summary up top.
+ */
+export async function cmdServiceStatus(_args) {
+    const { spawnSync } = await import("child_process");
+    if (process.platform === "linux") {
+        const r = spawnSync("systemctl", ["status", "agentnet", "--no-pager"], { encoding: "utf-8" });
+        process.stdout.write(r.stdout || "");
+        if (r.stderr)
+            process.stderr.write(r.stderr);
+        process.exit(r.status ?? 0);
+    }
+    if (process.platform === "darwin") {
+        const r = spawnSync("launchctl", ["list", "com.decentlan.agentnet"], { encoding: "utf-8" });
+        if ((r.status ?? 0) !== 0) {
+            console.log("Not loaded. Install with 'sudo agentnet service install'.");
+            return;
+        }
+        process.stdout.write(r.stdout || "");
+        return;
+    }
+    console.log(`'service status' isn't wired up for ${process.platform}.`);
+}

package/dist/cli/index.js

@@ -10,7 +10,7 @@ import { hideBin } from "yargs/helpers";
 // Belt-and-braces — also raise it here in case the CLI is run directly
 // (e.g. `node dist/cli/index.js` rather than via dist/index.js).
 EventEmitter.defaultMaxListeners = 100;
-import { cmdInit, cmdIdentityShow, cmdPeersList, cmdIpamAssign, cmdGrant, cmdRevoke, cmdResolve, cmdStatus, cmdUp, cmdAuditLog, cmdFriendRequest, cmdFriendAccept, cmdFriendsList, cmdFriendsPending, cmdFriendsAccept, cmdFriendsReject, cmdProxyEnable, cmdProxyDisable, cmdProxyStatus, cmdProxyAllowHost, cmdProxyRevokeHost, cmdProxyListHosts, cmdProxyUse, cmdDoraEnable, cmdDoraDisable, cmdDoraStatus, cmdDoraAutofriend, cmdDiag, cmdDnsInstall, cmdDnsHosts, } from "./commands.js";
+import { cmdInit, cmdIdentityShow, cmdPeersList, cmdIpamAssign, cmdGrant, cmdRevoke, cmdResolve, cmdStatus, cmdUp, cmdAuditLog, cmdFriendRequest, cmdFriendAccept, cmdFriendsList, cmdFriendsPending, cmdFriendsAccept, cmdFriendsReject, cmdProxyEnable, cmdProxyDisable, cmdProxyStatus, cmdProxyAllowHost, cmdProxyRevokeHost, cmdProxyListHosts, cmdProxyUse, cmdDoraEnable, cmdDoraDisable, cmdDoraStatus, cmdDoraAutofriend, cmdDiag, cmdDnsInstall, cmdDnsHosts, cmdServiceInstall, cmdServiceStatus, } from "./commands.js";
 async function main() {
     await yargs(hideBin(process.argv))
         .scriptName("agentnet")
@@ -97,6 +97,27 @@ async function main() {
     })
         .demandCommand(1, "Specify a dns subcommand (run 'agentnet dns --help')"), () => {
         // parent handler — never invoked because demandCommand
+    })
+        // Persistent system service — wraps systemctl (Linux) and
+        // launchctl (macOS) so a new operator runs ONE command to install
+        // + start + persist instead of hand-writing a unit/plist.
+        .command("service", "Install/uninstall/inspect the daemon as a system service (systemd on Linux, launchd on macOS)", (y) => y
+        .command("install", "Write the unit/plist, enable + start (needs sudo)", (yy) => yy
+        .option("uninstall", { type: "boolean", default: false, describe: "Reverse the install" })
+        .option("config-dir", { type: "string" }), async (argv) => {
+        await cmdServiceInstall({
+            uninstall: argv.uninstall,
+            configDir: argv["config-dir"],
+        });
+    })
+        .command("uninstall", "Stop and remove the system service (alias for 'service install --uninstall')", (yy) => yy.option("config-dir", { type: "string" }), async (argv) => {
+        await cmdServiceInstall({ uninstall: true, configDir: argv["config-dir"] });
+    })
+        .command("status", "Show service status (systemctl status / launchctl list)", (yy) => yy.option("config-dir", { type: "string" }), async (argv) => {
+        await cmdServiceStatus({ configDir: argv["config-dir"] });
+    })
+        .demandCommand(1, "Specify a service subcommand (run 'agentnet service --help')"), () => {
+        // parent handler — never invoked because demandCommand above
     })
         .command("up", "Start the daemon", (y) => y
         .option("name", { type: "string" })

package/dist/config/loader.d.ts

@@ -1,4 +1,17 @@
 import type { DecentAgentNetConfig } from "../types.js";
+/**
+ * Public dora server baked into `agentnet init` so an operator can join
+ * the canonical Decent AgentNet without first hunting down a registry
+ * address. Override by editing `dora.userids` (and re-running
+ * `agentnet dora enable --address <yours>`) — or by running a private
+ * dora and pointing your own peers at it.
+ *
+ * Both fields are required: the daemon needs `userid` to talk to the
+ * server over Carrier, and `address` so `agentnet init` can send the
+ * one-time friend-request that establishes the Carrier session.
+ */
+export declare const DEFAULT_DORA_USERID = "98rsHv17h8G6AP9RagyrBiT1kmw4cn8MFPEembS6ZVjv";
+export declare const DEFAULT_DORA_ADDRESS = "Jt7w1pKkyLT5GVue9h6ZPkjg1EeuuTbD6JVSLycXLsdm6nvBGSUd";
 export declare class ConfigLoader {
     static defaultConfigPath(): string;
     static defaultConfigDir(): string;

package/dist/config/loader.js

@@ -23,6 +23,19 @@ const DEFAULT_BOOTSTRAP_NODES = [
 const DEFAULT_EXPRESS_NODES = [
     { host: "lens.beagle.chat", port: 443, pk: "ECbs4GxwGzxGerNkmqDJFibEmevu8jAXqAZtikccvD95" },
 ];
+/**
+ * Public dora server baked into `agentnet init` so an operator can join
+ * the canonical Decent AgentNet without first hunting down a registry
+ * address. Override by editing `dora.userids` (and re-running
+ * `agentnet dora enable --address <yours>`) — or by running a private
+ * dora and pointing your own peers at it.
+ *
+ * Both fields are required: the daemon needs `userid` to talk to the
+ * server over Carrier, and `address` so `agentnet init` can send the
+ * one-time friend-request that establishes the Carrier session.
+ */
+export const DEFAULT_DORA_USERID = "98rsHv17h8G6AP9RagyrBiT1kmw4cn8MFPEembS6ZVjv";
+export const DEFAULT_DORA_ADDRESS = "Jt7w1pKkyLT5GVue9h6ZPkjg1EeuuTbD6JVSLycXLsdm6nvBGSUd";
 export class ConfigLoader {
     static defaultConfigPath() {
         return DEFAULT_CONFIG_FILE;
@@ -101,12 +114,16 @@ export class ConfigLoader {
             friends: {
                 autoAccept: true,
             },
-            // Dora integration is opt-in. Leave userids empty to fall back to
-            // manual ipam.yaml mode. Once a dora server's userid is added,
-            // the daemon registers itself on startup and pulls the roster.
+            // Dora integration is ON by default and points at the public
+            // canonical dora — `agentnet init` follows up with a one-time
+            // friend-request to its address, so a fresh install joins the
+            // shared network with zero additional commands. To run in
+            // private (no dora) mode: `agentnet dora disable`. To point at
+            // your own dora: `agentnet dora enable --address <addr>` (it
+            // replaces the default).
             dora: {
-                enabled: false,
-                userids: [],
+                enabled: true,
+                userids: [DEFAULT_DORA_USERID],
                 refreshIntervalMs: 60_000,
                 // Default: auto-friend every peer in the dora roster. Dora
                 // membership IS the trust statement — joining a dora means

package/dist/daemon/ipc.d.ts

@@ -39,9 +39,15 @@ export interface IpcHandlers {
     /** Reject (drop) a queued friend-request by userid. Doesn't
      *  notify the sender — they'll just see no acceptance. */
     friendsReject: (userid: string) => Promise<void>;
+    /** Re-read proxy allowlist from config and apply it to the running
+     *  proxy WITHOUT restarting the daemon. Lets `agentnet proxy
+     *  allow-host` take effect instantly instead of forcing a daemon
+     *  restart (which drops every Carrier session). Returns the applied
+     *  allowlist for the CLI to echo. */
+    proxyReload: () => Promise<Record<string, unknown>>;
 }
 export interface IpcRequest {
-    op: "friend-request" | "ping" | "diag" | "friends-pending" | "friends-accept" | "friends-reject";
+    op: "friend-request" | "ping" | "diag" | "friends-pending" | "friends-accept" | "friends-reject" | "proxy-reload";
     address?: string;
     hello?: string;
     userid?: string;

package/dist/daemon/ipc.js

@@ -144,6 +144,8 @@ export class IpcServer {
                 await this.handlers.friendsReject(req.userid);
                 return;
             }
+            case "proxy-reload":
+                return await this.handlers.proxyReload();
             default:
                 throw new Error(`unknown op: ${req.op}`);
         }

package/dist/daemon/server.d.ts

@@ -36,6 +36,7 @@ export declare class DaemonServer {
     private startedAt;
     private isRunning;
     private pidFile?;
+    private configDir;
     constructor(opts: DaemonOptions);
     start(): Promise<void>;
     stop(): Promise<void>;

package/dist/daemon/server.js

@@ -18,6 +18,7 @@ import { DnsServer } from "../dns/server.js";
 import { IpcServer, ipcSocketPath } from "./ipc.js";
 import { PendingFriendsStore } from "./pending-friends.js";
 import { Logger } from "../utils/logger.js";
+import { ConfigLoader } from "../config/loader.js";
 export class DaemonServer {
     config;
     useMockTun;
@@ -40,9 +41,13 @@ export class DaemonServer {
     startedAt = 0;
     isRunning = false;
     pidFile;
+    configDir;
     constructor(opts) {
         this.config = opts.config;
         this.useMockTun = opts.useMockTun ?? true; // Default to mock; override for production
+        // Remember where config.yaml lives so live-reload ops (e.g.
+        // proxy-reload) can re-read it without a daemon restart.
+        this.configDir = opts.configDir ?? ConfigLoader.defaultConfigDir();
         this.logger = new Logger({ prefix: "Daemon" });
     }
     async start() {
@@ -145,6 +150,31 @@ export class DaemonServer {
                         throw new Error(`No pending friend-request for userid ${userid}`);
                     // No-op at the Carrier level — sender just sees no acceptance.
                 },
+                proxyReload: async () => {
+                    // Re-read the proxy allowlist from disk and push it into the
+                    // running proxy without a daemon restart (which would drop
+                    // every Carrier session). If the proxy isn't running yet,
+                    // tell the caller so it can fall back to "restart needed".
+                    const fresh = await ConfigLoader.load(resolve(this.configDir, "config.yaml"));
+                    const allowHosts = fresh.proxy?.allowHosts ?? [];
+                    const allowConnectPorts = fresh.proxy?.allowConnectPorts;
+                    if (!this.connectProxy) {
+                        return {
+                            applied: false,
+                            reason: fresh.proxy?.enabled
+                                ? "proxy enabled in config but not running — restart the daemon once to start the listener"
+                                : "proxy is disabled — run 'agentnet proxy enable' then restart once",
+                        };
+                    }
+                    this.connectProxy.updateAllowlist(allowHosts, allowConnectPorts);
+                    // Keep the in-memory config in sync so a later diag reflects it.
+                    if (this.config.proxy) {
+                        this.config.proxy.allowHosts = allowHosts;
+                        if (allowConnectPorts)
+                            this.config.proxy.allowConnectPorts = allowConnectPorts;
+                    }
+                    return { applied: true, allowHosts };
+                },
                 diag: async () => {
                     // Snapshot of everything an operator needs to debug why
                     // packets aren't moving: forwarding counters, friend
@@ -413,26 +443,43 @@ export class DaemonServer {
             // explicitly enabled it via `agentnet proxy enable`. Binds to the
             // virtual IP so reach is gated by the existing per-peer ACL — we
             // don't add a second auth layer at the HTTP level.
+            //
+            // Bind to `tunIp` (the dora-ALLOCATED IP), NOT config.network.ip.
+            // They diverge when dora hands out an address different from the
+            // init default: the listener would try to bind config's
+            // 10.86.1.10 while the TUN is actually at 10.86.1.15, and
+            // Node throws EADDRNOTAVAIL because that address isn't local.
+            //
+            // Also: a proxy bind failure must NOT take down the whole daemon.
+            // Packet forwarding, DNS, dora, friends — all work fine without
+            // the proxy. Catch + log so an EADDRNOTAVAIL (or port-in-use)
+            // degrades gracefully to "no proxy" instead of a crash loop.
             if (this.config.proxy?.enabled) {
                 if (this.useMockTun) {
                     this.logger.warn("Proxy enabled but daemon is in mock-TUN mode; skipping proxy listener");
                 }
                 else {
-                    this.connectProxy = new ConnectProxy({
-                        bindIp: this.config.network.ip,
-                        port: this.config.proxy.port,
-                        allowHosts: this.config.proxy.allowHosts ?? [],
-                        allowConnectPorts: this.config.proxy.allowConnectPorts,
-                        resolvePeerName: (srcIp) => this.ipam.resolveIp(srcIp)?.name,
-                        onTunnelOpen: ({ src, srcName, target }) => {
-                            this.auditLog.logProxyOpen({ srcIp: src, srcName, target });
-                        },
-                        onTunnelClose: ({ src, srcName, target, bytesTransferred }) => {
-                            this.auditLog.logProxyClose({ srcIp: src, srcName, target, bytesTransferred });
-                        },
-                    });
-                    await this.connectProxy.start();
-                    this.logger.info(`Proxy listening on ${this.config.network.ip}:${this.config.proxy.port}`);
+                    try {
+                        this.connectProxy = new ConnectProxy({
+                            bindIp: tunIp,
+                            port: this.config.proxy.port,
+                            allowHosts: this.config.proxy.allowHosts ?? [],
+                            allowConnectPorts: this.config.proxy.allowConnectPorts,
+                            resolvePeerName: (srcIp) => this.ipam.resolveIp(srcIp)?.name,
+                            onTunnelOpen: ({ src, srcName, target }) => {
+                                this.auditLog.logProxyOpen({ srcIp: src, srcName, target });
+                            },
+                            onTunnelClose: ({ src, srcName, target, bytesTransferred }) => {
+                                this.auditLog.logProxyClose({ srcIp: src, srcName, target, bytesTransferred });
+                            },
+                        });
+                        await this.connectProxy.start();
+                        this.logger.info(`Proxy listening on ${tunIp}:${this.config.proxy.port}`);
+                    }
+                    catch (err) {
+                        this.connectProxy = undefined;
+                        this.logger.error(`Proxy failed to start on ${tunIp}:${this.config.proxy.port} — continuing without it: ${err instanceof Error ? err.message : err}`);
+                    }
                 }
             }
             this.isRunning = true;

package/dist/proxy/connect-proxy.d.ts

@@ -65,6 +65,17 @@ export declare class ConnectProxy {
     start(): Promise<void>;
     stop(): Promise<void>;
     getStats(): ConnectProxyStats;
+    /**
+     * Update the host allowlist (and optionally the port allowlist) of a
+     * RUNNING proxy without restarting it. handleConnect reads
+     * `this.opts.allowHosts` / `allowConnectPorts` at request time, so a
+     * plain field swap takes effect on the next CONNECT — no need to tear
+     * down the listener or, more importantly, the daemon's Carrier
+     * sessions. Lets `agentnet proxy allow-host` apply instantly instead
+     * of forcing a daemon restart that would drop every peer session and
+     * trigger a slow reconvergence storm.
+     */
+    updateAllowlist(allowHosts: string[], allowConnectPorts?: number[]): void;
     private handleConnect;
     private refuse;
 }

package/dist/proxy/connect-proxy.js

@@ -86,6 +86,23 @@ export class ConnectProxy {
     getStats() {
         return { ...this.stats };
     }
+    /**
+     * Update the host allowlist (and optionally the port allowlist) of a
+     * RUNNING proxy without restarting it. handleConnect reads
+     * `this.opts.allowHosts` / `allowConnectPorts` at request time, so a
+     * plain field swap takes effect on the next CONNECT — no need to tear
+     * down the listener or, more importantly, the daemon's Carrier
+     * sessions. Lets `agentnet proxy allow-host` apply instantly instead
+     * of forcing a daemon restart that would drop every peer session and
+     * trigger a slow reconvergence storm.
+     */
+    updateAllowlist(allowHosts, allowConnectPorts) {
+        this.opts.allowHosts = allowHosts;
+        if (allowConnectPorts)
+            this.opts.allowConnectPorts = allowConnectPorts;
+        this.logger.info(`Allowlist updated live: ${allowHosts.length} host glob(s)` +
+            (allowConnectPorts ? `, ports ${allowConnectPorts.join(",")}` : ""));
+    }
     handleConnect(req, clientSocket, head) {
         const src = clientSocket.remoteAddress ?? "?";
         const srcName = this.opts.resolvePeerName?.(src);

package/docs/INSTALL.md

@@ -102,33 +102,146 @@ ping <peer-name>.decent        # if you ran 'dns install'
 
 ## Running the daemon as a service
 
-There's no built-in init script. Pattern is the same as any
-foreground binary; rough sketches:
+The daemon is a foreground binary. Pick one of:
 
-### systemd (Linux)
+### Option A — `nohup` (fastest; no auto-restart)
 
-```ini
-# /etc/systemd/system/agentnet.service
+```bash
+# pre-create the log so the unprivileged user can tail it
+sudo touch /var/log/agentnet.log
+sudo chmod 666 /var/log/agentnet.log
+
+# IMPORTANT: wrap the whole pipeline in `sudo sh -c '...'`.
+# Otherwise `>>` is interpreted by your unprivileged shell and the
+# redirect fails with "Permission denied" before sudo elevates.
+sudo sh -c 'nohup agentnet up --real-tun --config-dir /home/YOURUSER/.agentnet >> /var/log/agentnet.log 2>&1 &'
+
+# verify
+ps -ef | grep -E 'agentnet up|tun-helper' | grep -v grep
+tail -f /var/log/agentnet.log
+
+# stop
+sudo pkill -f 'agentnet up'; sudo pkill -f tun-helper
+```
+
+Always pass `--config-dir /home/YOURUSER/.agentnet` when launching with
+`sudo` — `sudo` changes `$HOME` to `/root`, so without an explicit
+`--config-dir` the daemon (and any one-off CLI invocations) will look
+at `/root/.agentnet/` and report "Not initialized."
+
+### Option B — systemd (Linux, persistent + auto-restart)
+
+```bash
+sudo tee /etc/systemd/system/agentnet.service <<'EOF'
 [Unit]
 Description=Decent AgentNet daemon
 After=network-online.target
 Wants=network-online.target
 
 [Service]
-ExecStart=/usr/bin/agentnet up --real-tun --config-dir /home/<you>/.agentnet
+Type=simple
 User=root
+ExecStart=/usr/local/bin/agentnet up --real-tun --config-dir /home/YOURUSER/.agentnet
 Restart=on-failure
 RestartSec=5
+StandardOutput=append:/var/log/agentnet.log
+StandardError=append:/var/log/agentnet.log
 
 [Install]
 WantedBy=multi-user.target
+EOF
+
+sudo systemctl daemon-reload
+sudo systemctl enable --now agentnet
+sudo systemctl status agentnet
+journalctl -u agentnet -f      # live logs (alternative to /var/log/agentnet.log)
+```
+
+Persists across reboots. If you ever previously launched via
+`systemd-run --unit=agentnet ...` (transient unit), the unit file
+above replaces it cleanly.
+
+### Option C — launchd (macOS, persistent + auto-restart)
+
+```bash
+sudo tee /Library/LaunchDaemons/com.decentlan.agentnet.plist <<EOF
+<?xml version="1.0"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>com.decentlan.agentnet</string>
+  <key>UserName</key><string>root</string>
+  <key>ProgramArguments</key><array>
+    <string>/usr/local/bin/agentnet</string>
+    <string>up</string>
+    <string>--real-tun</string>
+    <string>--config-dir</string>
+    <string>/Users/YOURUSER/.agentnet</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>/var/log/agentnet.log</string>
+  <key>StandardErrorPath</key><string>/var/log/agentnet.log</string>
+</dict></plist>
+EOF
+sudo launchctl load /Library/LaunchDaemons/com.decentlan.agentnet.plist
+tail -f /var/log/agentnet.log
+```
+
+`sudo launchctl unload /Library/LaunchDaemons/com.decentlan.agentnet.plist`
+to stop. Drop the `.plist` file to disable persistence.
+
+## Running CLI commands once the daemon is up
+
+The CLI talks to the daemon over a Unix socket in the config-dir.
+Most commands (`diag`, `ipam list`, `friends list`, `friends pending`,
+`resolve`, `dora autofriend`) just read or write config files — they
+**don't need sudo**:
+
+```bash
+agentnet diag
+agentnet ipam list
+agentnet friends list
+agentnet dora autofriend all
+```
+
+The few that DO need sudo (writing `/etc/resolver/` on macOS, or
+`/etc/dnsmasq.d/` on Linux) require an explicit `--config-dir`
+because `sudo`'s `$HOME` is `/root`:
+
+```bash
+sudo agentnet dns install --config-dir /home/YOURUSER/.agentnet
+```
+
+## DNS on Linux when dnsPort isn't 53
+
+`agentnet init` defaults to `dnsPort: 5354` (5353 is reserved for
+mDNS / Avahi; we step around it). systemd-resolved only forwards to
+upstreams on port 53, so `agentnet dns install` on Linux will warn
+and refuse rather than write a broken config. Two workarounds:
+
+```bash
+# Workaround 1 — static /etc/hosts (simple; re-run on roster changes)
+agentnet dns hosts | sudo tee -a /etc/hosts > /dev/null
+
+# Workaround 2 — dnsmasq forward
+agentnet dns install     # prints a dnsmasq snippet; paste into
+                         # /etc/dnsmasq.d/decent.conf, restart dnsmasq
 ```
 
-### launchd (macOS)
+macOS has no port-53 restriction — `agentnet dns install` works
+out of the box there.
+
+## Troubleshooting
 
-`/Library/LaunchDaemons/com.decent.agentnet.plist` — see
-`man launchd.plist`. Important: `Sudo` env isn't a thing in
-launchd, so put the daemon under `<key>UserName</key><string>root</string>`.
+| symptom | likely cause | fix |
+|---|---|---|
+| `Not initialized. Run 'agentnet init' first.` after running with sudo | `sudo` set `$HOME=/root`; CLI is looking at `/root/.agentnet/` | add `--config-dir /home/YOURUSER/.agentnet` |
+| `/var/log/agentnet.log: Permission denied` when starting with `sudo nohup ... >> ...` | `>>` runs in your unprivileged shell before sudo elevates | wrap in `sudo sh -c '...'`, OR pre-create the log file with `chmod 666` |
+| `Unit agentnet.service not found.` after a successful `systemctl restart` | previous launch was a transient `systemd-run` unit (auto-removed on stop) | install the persistent unit file (Option B above) |
+| `dora friend is offline` for >60s right after restart | Carrier session re-handshake takes 30–90s; not a real failure | wait, or `agentnet diag` to confirm `friends[].status == "online"` |
+| `ipam list` shows only the self entry | dora roster fetch hasn't merged yet, or dora server is down | wait one refresh interval (60s default), then check the dora server; also confirm `dora.autoFriend` isn't `none` |
+| `ping <peer>.decent` resolves but times out | TUN routing OK but the remote daemon is older without the auto-learn-IPAM fix | upgrade the remote to `@decentnetwork/lan@0.1.13+` |
+| `ping <peer>.decent` fails with `Unknown host` even though `nslookup -port=5354 <peer>.decent 127.0.0.1` works | macOS hasn't reloaded `/etc/resolver/` | `sudo killall -HUP mDNSResponder` |
 
 ## Uninstall
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/lan",
-  "version": "0.1.18",
+  "version": "0.1.22",
   "description": "Private virtual LAN for self-hosted services and AI agents, built on Elastos Carrier. NAT-traversal, name service, ACL, all over a peer-to-peer mesh — no public IP required.",
   "type": "module",
   "main": "./dist/index.js",