@bivy/bivy 0.20.1-staging.8 → 0.20.1

package/bin/access-view.mjs

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// Terminal views of the node's access report (src/access.ts): the full
+// `bivy access` screen and the one-line summary `bivy status` shows.
+
+const REACH_WORD = ["", "on your tailnet", "from anywhere"];
+
+/** "Tailscale + Bivy hosted", or "This machine only". */
+export function activeLabel(report) {
+  const on = report.setups.filter((s) => s.active && s.id !== "local");
+  return on.length ? on.map((s) => s.label).join(" + ") : "This machine only";
+}
+
+function labelOf(report, id) {
+  return report.setups.find((s) => s.id === id)?.label ?? id;
+}
+
+/** `access: Tailscale — next: Bivy hosted` for `bivy status`. */
+export function accessLine(report) {
+  const next = report.next.filter((n) => n.id !== "server").map((n) => labelOf(report, n.id));
+  return `${activeLabel(report)}${next.length ? ` — next: ${next.join(" or ")} ('bivy access')` : ""}`;
+}
+
+/** The `bivy access` screen as lines; `paint` supplies colors. */
+export function accessScreen(report, paint) {
+  const lines = [`${paint.bold("Access:")} ${activeLabel(report)}`];
+  if (report.tailscaleUrl) lines.push(`  ${paint.dim("tailnet")}  ${report.tailscaleUrl}`);
+  if (report.controlPlaneUrl) lines.push(`  ${paint.dim("app")}      ${report.controlPlaneUrl}`);
+  lines.push("");
+  for (const feature of report.features) {
+    const reach = report.reach[feature.id];
+    lines.push(`  ${reach ? paint.green("✓") : paint.dim("✗")} ${feature.label}${reach ? paint.dim(` ${REACH_WORD[reach]}`.trimEnd()) : ""}`);
+  }
+  if (report.next.length) {
+    lines.push("", paint.bold("Next:"));
+    for (const step of report.next) {
+      const setup = report.setups.find((s) => s.id === step.id);
+      lines.push(`  ${paint.cyan((setup?.command ?? "").padEnd(26))} ${setup?.label}`, `  ${" ".repeat(26)} ${paint.dim(`adds ${step.addsText}`)}`);
+    }
+  }
+  lines.push("", paint.dim("Setups stack: adding one never takes away another. 'bivy access local' turns remote access off."));
+  return lines;
+}

package/bin/bivy.mjs

@@ -40,6 +40,7 @@ import { nativeResumeRef, resolveSessionsLimit, truncateSavedSessions } from "./
 import { renderManagedBlock, upsertManagedBlock, removeManagedBlock, rcFileForShell } from "./shim-path.mjs";
 import { removeInstallAndState } from "./uninstall-paths.mjs";
 import { findAvailablePort, reconcilePort } from "./port-picker.mjs";
+import { accessLine, accessScreen } from "./access-view.mjs";
 import { parseTailscaleStatus, serveConflict, serveFailureHint, serveOffArgs, serveOnArgs, serveState } from "./tailscale.mjs";
 import { resolveAttachSessionId } from "./attach-session-id.mjs";
 import { detectInstallKind as classifyInstallKind, managedInstall, npmGlobalPrefix } from "./install-kind.mjs";
@@ -4527,6 +4528,8 @@ async function cmdTokenSetup() {
 }
 
 async function cmdSetup(args = []) {
+  // Set by the access question; `bivy tailscale` runs once the node is up.
+  let wantTailscale = false;
   if (args.includes("-h") || args.includes("--help")) {
     console.log("Usage: bivy setup\n\nFirst-run wizard: agent choice, model login, remote access + sign-in, and background service. Workspace and port get safe defaults. Re-run later to change the default agent or remote access.");
     return;
@@ -4634,18 +4637,22 @@ async function cmdSetup(args = []) {
     // (BIVY_CONTROL_PLANE_URL / BIVY_RELAY_URL then pre-fill the URL prompts below).
     const nodeClaimCode = process.env.BIVY_NODE_CLAIM_CODE?.trim();
     const selfHostEnv = !nodeClaimCode && Boolean((process.env.BIVY_CONTROL_PLANE_URL || "").trim() || (process.env.BIVY_RELAY_URL || "").trim());
+    // Tailscale is offered only where it's installed; it needs no account.
+    const tailscaleInstalled = runTailscale(["version"]) !== null;
     const syncChoice = nodeClaimCode ? "h" : await askChoice(
-      "Remote access",
+      "How will you reach this machine?",
       [
-        { key: "h", label: "hosted (recommended — sign in with GitHub or email; nothing caps your local usage)" },
-        { key: "s", label: "self-hosted (your own control plane + relay)" },
-        { key: "l", label: "local only for now (terminal CLI only; run 'bivy relay:setup' later)" },
+        { key: "h", label: "Bivy hosted (recommended — sign in with GitHub or email; every machine, from anywhere)" },
+        ...(tailscaleInstalled ? [{ key: "t", label: "Tailscale (your devices over your tailnet; no account, nothing in between)" }] : []),
+        { key: "s", label: "your own server (a Bivy server you run)" },
+        { key: "l", label: "this machine only for now (add more any time with 'bivy access')" },
       ],
       selfHostEnv ? "s" : "h",
     );
+    wantTailscale = syncChoice === "t";
     const relayArgs = [];
-    if (syncChoice === "l") {
-      console.log(c.dim("\nSkipping remote access. Enable it any time with 'bivy relay:setup'."));
+    if (syncChoice === "l" || syncChoice === "t") {
+      console.log(c.dim(`\n${syncChoice === "t" ? "Tailscale is turned on once the node is running." : "Skipping remote access."} 'bivy access' shows every option later.`));
     }
     if (syncChoice === "s") {
       const endpoints = await getHostedEndpoints();
@@ -4655,7 +4662,7 @@ async function cmdSetup(args = []) {
       if (relayWs.trim()) relayArgs.push("--relay", relayWs.trim());
     }
 
-    if (syncChoice !== "l") {
+    if (syncChoice !== "l" && syncChoice !== "t") {
       if (!nodeClaimCode) {
         const loginChoice = await askChoice(
           "Remote login",
@@ -4704,7 +4711,7 @@ async function cmdSetup(args = []) {
       setupSession = consumeSetupSession();
     }
   } else {
-    console.log(c.dim("\nRemote access already configured. Re-run 'bivy relay:setup' to change sync or sign-in."));
+    console.log(c.dim("\nRemote access already configured. 'bivy access' shows it and the other options."));
   }
 
   // GitHub App — connect it from the web app (Settings → GitHub App) or with
@@ -4743,6 +4750,19 @@ async function cmdSetup(args = []) {
     }
   }
 
+  // The terminal path to the same loop: the agent's own command starts a Bivy
+  // session, so work begun in a terminal shows up in the app and reaches the
+  // phone. Offered after sign-in, which runs the real agent.
+  const shimAgent = setupAgent?.command;
+  if (agentReady && shimAgent && AGENT_INTEGRATIONS.has(shimAgent) && !loadShims().shims[shimAgent]) {
+    console.log(`\nWhen you type '${shimAgent}' in a terminal, Bivy can run it as a session: it shows up in the app, and your phone hears when it finishes or needs you.`);
+    if (await askYesNo(`Start a Bivy session whenever you run '${shimAgent}'?`, true)) {
+      rl.pause();
+      await run(nodeBin, [selfScript, "shim", "install", shimAgent], { env: process.env });
+      rl.resume();
+    }
+  }
+
   // Materialize canonical typed config before starting/restarting the daemon,
   // so this setup run's workspace/port/agent choices are effective immediately.
   // Existing config keeps every advanced field.
@@ -4784,6 +4804,7 @@ async function cmdSetup(args = []) {
     ? Boolean(liveReadiness?.credential?.ok ?? hasModelConfig(finalConfig))
     : agentAuthReady;
   const repoReady = Boolean(liveReadiness?.repository?.ok);
+  if (wantTailscale) await cmdTailscale(["on"]).catch((error) => console.log(c.yellow(`Tailscale setup didn't finish: ${error?.message || error}. Run 'bivy access tailscale' to retry.`)));
   console.log(c.bold(c.green("\n  ✓ Node running. Check first-task readiness below.\n")));
   console.log(`  ${c.green("✓")} node reachable at ${url(finalConfig)}`);
   console.log(`  ${agentReady ? c.green("✓") : c.yellow("!")} runtime ${agentReady ? `${setupAgent?.label || "Pi"} available` : "not installed — run 'bivy agents:install'"}`);
@@ -4792,7 +4813,7 @@ async function cmdSetup(args = []) {
   const ghReady = githubConnected(finalConfig);
   console.log(`  ${ghReady ? c.green("✓") : c.dim("○")} GitHub ${ghReady ? "connected — your repos will list in the app" : c.dim("optional — connect later in the app under Settings → GitHub App")}`);
   console.log(`  ${agentReady && modelReady && repoReady ? c.green("✓") : c.yellow("!")} first task ${agentReady && modelReady && repoReady ? "ready to try" : "blocked by the stage above"}`);
-  console.log(`  ${fs.existsSync(relayConfigPath) ? c.green("✓") : c.yellow("!")} remote ${fs.existsSync(relayConfigPath) ? "configured" : "not configured — run 'bivy relay:setup'"}\n`);
+  console.log(`  ${fs.existsSync(relayConfigPath) || fs.existsSync(tailscaleConfigPath) ? c.green("✓") : c.dim("○")} access ${fs.existsSync(relayConfigPath) || fs.existsSync(tailscaleConfigPath) ? "set up — 'bivy access' shows what it gives you" : "this machine only — 'bivy access' shows the options"}\n`);
   // Get the user into the product immediately; terminal commands are the
   // fallback/next-step checklist after the remote app has been opened or linked.
   await finishSetupRemote(finalConfig, setupSession);
@@ -4979,8 +5000,10 @@ async function cmdStatus(args = []) {
   const relay = loadRelayConfig();
   const relaySt = status?.relay;
   const relayConfigured = Boolean(relaySt?.configured || relay);
+  const access = reachable ? await fetchAccess(config).catch(() => null) : null;
+  if (access) console.log(`  access:    ${accessLine(access)}`);
   if (!relayConfigured) {
-    console.log(`  remote:    ${c.dim("local only")}  ${c.dim("('bivy relay:setup' to enable remote access)")}`);
+    if (!access) console.log(`  remote:    ${c.dim("this machine only")}  ${c.dim("('bivy access' to see the options)")}`);
   } else {
     // The live link state is only knowable when the node is running; if it's
     // down we can say it's configured but not whether it's currently connected.
@@ -5175,7 +5198,7 @@ async function cmdDoctor(args = []) {
   const relayApp = status?.relay?.controlPlaneUrl;
   const relayErr = status?.relay?.lastError;
   const relayLine = !relayConfigured
-    ? c.dim("local only — 'bivy relay:setup' to enable")
+    ? c.dim("this machine only — 'bivy access' to see the options")
     : relayConnected
       ? c.green("relay connected") + (relayApp ? c.dim(`  ${relayApp}`) : "")
       : c.yellow("configured, not connected") + (relayErr ? c.dim(`  (${relayErr})`) : "");
@@ -5815,7 +5838,7 @@ async function cmdTailscale(args = []) {
     process.exitCode = EXIT.unavailable;
     return;
   }
-  const { running, hostname } = parseTailscaleStatus(status.stdout);
+  const { running, hostname, owner } = parseTailscaleStatus(status.stdout);
   if (!running || !hostname) {
     console.log(`${c.yellow("Tailscale isn't connected.")} Sign in with ${c.cyan("sudo tailscale up")}, then run ${c.cyan("bivy tailscale")} again.`);
     process.exitCode = EXIT.unavailable;
@@ -5828,7 +5851,7 @@ async function cmdTailscale(args = []) {
     process.exitCode = EXIT.conflict;
     return;
   }
-  fs.writeFileSync(tailscaleConfigPath, `${JSON.stringify({ port, hostname }, null, 2)}\n`, { mode: 0o600 });
+  fs.writeFileSync(tailscaleConfigPath, `${JSON.stringify({ port, hostname, ...(owner ? { owner } : {}) }, null, 2)}\n`, { mode: 0o600 });
   const reload = await localApi(config, "/api/direct/reload", { method: "POST", body: "{}" });
   const served = runTailscale(serveOnArgs(port));
   if (!served?.ok) {
@@ -5841,12 +5864,83 @@ async function cmdTailscale(args = []) {
     return;
   }
   console.log(c.bold(c.green(`\n  Bivy is on https://${hostname}\n`)));
-  console.log(c.dim("  Only devices on your tailnet can reach it. Pair each one once with a link from 'bivy tailscale pair'."));
+  console.log(c.dim(owner
+    ? `  Only devices on your tailnet can reach it. Yours (signed in as ${owner}) are let in without pairing;\n  anyone else's pairs once with a link from 'bivy tailscale pair'.`
+    : "  Only devices on your tailnet can reach it. This machine is tagged, so each device pairs once with a link from 'bivy tailscale pair'."));
   if (!reload?.webApp) console.log(c.yellow("  This install has no built web app, so the address serves the API only. Run 'pnpm run build:web' in a source checkout."));
   console.log("");
+  if (owner) {
+    console.log(`Open ${c.cyan(`https://${hostname}`)} on any of your devices.\n`);
+    return;
+  }
   await printPairLink(config);
 }
 
+async function fetchAccess(config) {
+  return localApi(config, "/api/access/get", { method: "POST", body: "{}" });
+}
+
+// `bivy access` — how this machine can be reached (this machine only,
+// Tailscale, Bivy hosted, your own server), what that gives you, and the next
+// step. The node owns the table (src/access.ts); this only renders and routes.
+async function cmdAccess(args = []) {
+  const [verb, target] = args.filter((a) => !a.startsWith("-"));
+  if (args.includes("-h") || args.includes("--help") || (verb && !["local", "tailscale", "hosted", "server"].includes(verb))) {
+    console.log(`Usage: bivy access [--json]
+       bivy access tailscale              reach this machine from your devices over Tailscale
+       bivy access hosted                 sign in to Bivy hosted: every machine, from anywhere
+       bivy access server <url> [--relay <wss-url>]   the same, through your own server
+       bivy access local                  turn remote access off
+
+Setups stack: Tailscale can stay on alongside hosted or your own server.`);
+    if (verb && !["local", "tailscale", "hosted", "server"].includes(verb)) process.exitCode = EXIT.usage;
+    return;
+  }
+  const config = loadConfig();
+  if (!(await ensureNodeRunning(config))) {
+    console.error(c.red(`Could not start the Bivy node at ${url(config)}.`));
+    process.exitCode = EXIT.unavailable;
+    return;
+  }
+  const report = await fetchAccess(config);
+
+  if (!verb) {
+    if (wantsJson(args)) { console.log(JSON.stringify(report, null, 2)); return; }
+    console.log(`\n${accessScreen(report, c).join("\n")}\n`);
+    return;
+  }
+  if (verb === "tailscale") return cmdTailscale(["on"]);
+  if (verb === "hosted" || verb === "server") {
+    const linked = report.setups.find((s) => s.active && (s.id === "hosted" || s.id === "server"));
+    if (linked && linked.id === verb && verb === "hosted") {
+      console.log(`Already on ${linked.label}${report.controlPlaneUrl ? ` (${report.controlPlaneUrl})` : ""}.`);
+      return;
+    }
+    if (linked) console.log(c.yellow(`This machine is on ${linked.label}${report.controlPlaneUrl ? ` (${report.controlPlaneUrl})` : ""}. Switching keeps everything on this machine; your devices sign in again at the new address.`));
+    if (verb === "hosted") return cmdRelaySetup([]);
+    if (!target) {
+      console.log(`Usage: bivy access server <url> [--relay <wss-url>]\n\nThe address of your Bivy server, e.g. https://bivy.example.com. Set one up with docs/self-host-quickstart.md.`);
+      process.exitCode = EXIT.usage;
+      return;
+    }
+    let appUrl;
+    try { appUrl = new URL(/^https?:\/\//.test(target) ? target : `https://${target}`); } catch { appUrl = null; }
+    if (!appUrl) { console.error(c.red(`Not a URL: ${target}`)); process.exitCode = EXIT.usage; return; }
+    // Bivy's server installs serve the relay at /relay on the app's own domain.
+    const relayUrl = argValue(args, "relay") || `${appUrl.protocol === "http:" ? "ws" : "wss"}://${appUrl.host}/relay`;
+    return cmdRelaySetup(["--control-plane", appUrl.origin, "--relay", relayUrl]);
+  }
+  // local: turn off every remote setup that is on.
+  const on = report.setups.filter((s) => s.active && s.id !== "local");
+  if (!on.length) { console.log("Already this machine only."); return; }
+  const rl = createPrompter();
+  const yes = await rl.askYesNo(`Turn off ${on.map((s) => s.label).join(" and ")}? Sessions and credentials on this machine stay.`, false);
+  rl.close();
+  if (!yes) return;
+  if (on.some((s) => s.id === "tailscale")) await cmdTailscale(["off"]);
+  if (on.some((s) => s.id === "hosted" || s.id === "server")) await cmdAccountLogout([]);
+}
+
 function printUninstallHelp() {
   console.log(`
 ${c.bold("bivy uninstall")} — remove Bivy and all its data from this machine
@@ -6453,6 +6547,9 @@ Unlike 'bivy run', these commands operate on governed background Runs with check
     case "tailscale":
       await cmdTailscale(args);
       break;
+    case "access":
+      await cmdAccess(args);
+      break;
     case "relay:setup":
       await cmdRelaySetup(args);
       break;

package/bin/cli-commands.mjs

@@ -106,6 +106,7 @@ export const COMMANDS = [
   { name: "token", group: "node", scope: "node", usage: "token", summary: "Print a device token for this node" },
   { name: "open", group: "node", scope: "node", usage: "open", summary: "Open the remote web app" },
   { name: "link", group: "node", scope: "node", usage: "link", summary: "Show a web app link as a QR code in the terminal" },
+  { name: "access", group: "node", scope: "node", json: true, usage: "access [local|tailscale|hosted|server <url>]", summary: "How this machine can be reached, what that gives you, and the next step", subcommands: ["local", "tailscale", "hosted", "server"] },
   { name: "tailscale", group: "node", scope: "node", usage: "tailscale [on|pair|status|devices|revoke|off]", summary: "Reach this machine over Tailscale, with no server in between", subcommands: ["on", "pair", "status", "devices", "revoke", "off"] },
   { name: "relay:setup", group: "node", scope: "node", usage: "relay:setup", summary: "Enable secure remote web app access" },
   { name: "uninstall", group: "node", scope: "node", usage: "uninstall [--keep-sessions] [--dry-run]", summary: "Remove Bivy and all its data" },

package/bin/tailscale.mjs

@@ -7,12 +7,19 @@
 /** The one HTTPS port Bivy claims on the machine's tailnet name. */
 export const SERVE_HTTPS_PORT = 443;
 
-/** `{ running, hostname }` from `tailscale status --json` output. */
+/**
+ * `{ running, hostname, owner }` from `tailscale status --json` output. `owner`
+ * is the login of the user this machine belongs to, or null for a tagged
+ * machine (owned by tags, not a person).
+ */
 export function parseTailscaleStatus(text) {
   let status;
-  try { status = JSON.parse(text); } catch { return { running: false, hostname: null }; }
+  try { status = JSON.parse(text); } catch { return { running: false, hostname: null, owner: null }; }
   const hostname = String(status?.Self?.DNSName ?? "").replace(/\.$/, "") || null;
-  return { running: status?.BackendState === "Running", hostname };
+  const tagged = Array.isArray(status?.Self?.Tags) && status.Self.Tags.length > 0;
+  const login = status?.User?.[String(status?.Self?.UserID)]?.LoginName;
+  const owner = !tagged && typeof login === "string" && login.includes("@") ? login : null;
+  return { running: status?.BackendState === "Running", hostname, owner };
 }
 
 /** Where `tailscale serve` should send the machine's HTTPS traffic. */

package/dist/access.js

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// How this machine can be reached, as one table: the setups (this machine only,
+// Tailscale, Bivy hosted, your own server), what each gives you, and which are
+// active here. `bivy access`, `bivy status`, setup and the app all render this
+// report, so they always agree. Setups stack: each only adds to the ones before.
+export const ACCESS_FEATURES = [
+    { id: "devices", label: "Your phone and other devices" },
+    { id: "machines", label: "All your machines in one app" },
+    { id: "push", label: "Push notifications" },
+    { id: "sharing", label: "Shareable app previews" },
+];
+export const ACCESS_SETUPS = [
+    { id: "local", label: "This machine only", summary: "The terminal and a browser on this machine.", gives: { devices: 0, machines: 0, push: 0, sharing: 0 } },
+    { id: "tailscale", label: "Tailscale", summary: "Your devices reach your machines over your tailnet. No account, nothing in between.", command: "bivy access tailscale", gives: { devices: 1, machines: 1, push: 0, sharing: 0 } },
+    { id: "hosted", label: "Bivy hosted", summary: "Sign in once. Sessions stay end-to-end encrypted.", command: "bivy access hosted", gives: { devices: 2, machines: 2, push: 2, sharing: 2 } },
+    { id: "server", label: "Your own server", summary: "Like hosted, on a server you control.", command: "bivy access server <url>", gives: { devices: 2, machines: 2, push: 2, sharing: 2 } },
+];
+/** "a, b and c" (or "a and b"). */
+function and(items) {
+    return items.length < 2 ? items[0] ?? "" : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+}
+const origin = (url) => {
+    try {
+        return url ? new URL(url).origin : "";
+    }
+    catch {
+        return "";
+    }
+};
+/** Which setups are active, from what the node has on disk. */
+export function activeSetups(inputs) {
+    const active = ["local"];
+    if (inputs.tailscaleHostname)
+        active.push("tailscale");
+    const relay = inputs.relay;
+    if (relay?.room && relay.roomToken)
+        active.push("server");
+    else if (relay?.controlPlaneUrl)
+        active.push(origin(relay.controlPlaneUrl) === origin(inputs.hostedControlPlane) ? "hosted" : "server");
+    return active;
+}
+export function accessReport(inputs) {
+    const active = activeSetups(inputs);
+    const reach = {};
+    for (const { id } of ACCESS_FEATURES) {
+        reach[id] = Math.max(...ACCESS_SETUPS.filter((s) => active.includes(s.id)).map((s) => s.gives[id]));
+    }
+    // Hosted and your own server are alternatives: once one is on, neither is a next step.
+    const linked = active.includes("hosted") || active.includes("server");
+    const next = ACCESS_SETUPS
+        .filter((s) => !active.includes(s.id) && !(linked && (s.id === "hosted" || s.id === "server")))
+        .map((s) => {
+        const adds = ACCESS_FEATURES.filter((f) => s.gives[f.id] > reach[f.id]);
+        // What you already have on your tailnet only widens: say "from anywhere" once for those.
+        const widened = adds.filter((f) => reach[f.id] === 1).map((f) => f.label.toLowerCase());
+        const fresh = adds.filter((f) => reach[f.id] === 0).map((f) => f.label.toLowerCase());
+        const phrases = [...(widened.length ? [`${and(widened)} from anywhere`] : []), ...fresh];
+        return { id: s.id, adds: adds.map((f) => f.id), addsText: and(phrases) };
+    })
+        .filter((s) => s.adds.length > 0);
+    return {
+        features: ACCESS_FEATURES,
+        setups: ACCESS_SETUPS.map((s) => ({ ...s, active: active.includes(s.id) })),
+        active,
+        reach,
+        next,
+        ...(inputs.tailscaleHostname ? { tailscaleUrl: `https://${inputs.tailscaleHostname}` } : {}),
+        ...(inputs.relay?.controlPlaneUrl ? { controlPlaneUrl: inputs.relay.controlPlaneUrl } : {}),
+    };
+}

package/dist/apps/listeners.js

@@ -19,11 +19,39 @@ export async function scanListeners(workspace, platform = process.platform) {
     }
     const found = platform === "linux" ? await scanProc(root) : platform === "darwin" ? await scanLsof(root) : [];
     const byPort = new Map();
-    for (const offer of found)
+    for (const { cwd: _cwd, ...offer } of found)
         if (offer.pid !== process.pid && offer.port >= 1024 && !byPort.has(offer.port))
             byPort.set(offer.port, offer);
     return [...byPort.values()].sort((a, b) => a.port - b.port);
 }
+/** Servers running anywhere under `root` (the owner's home), each with the
+ * project it runs in: what a first session can open before it has a folder.
+ * Processes running in `root` itself or in Bivy's own data folders aren't apps. */
+export async function scanMachineListeners(root, bivyDirs = [path.join(root, ".bivy")], platform = process.platform) {
+    let top;
+    try {
+        top = await fs.realpath(root);
+    }
+    catch {
+        return [];
+    }
+    const found = platform === "linux" ? await scanProc(top) : platform === "darwin" ? await scanLsof(top) : [];
+    const byPort = new Map();
+    for (const { cwd, ...offer } of found) {
+        if (offer.pid === process.pid || offer.port < 1024 || byPort.has(offer.port) || cwd === top || bivyDirs.includes(cwd))
+            continue;
+        byPort.set(offer.port, { ...offer, project: await projectOf(cwd, top) });
+    }
+    return [...byPort.values()].sort((a, b) => a.port - b.port);
+}
+/** The nearest folder at or above `dir` (below `top`) with a .git, else `dir`. */
+async function projectOf(dir, top) {
+    for (let at = dir; inside(top, at) && at !== top; at = path.dirname(at)) {
+        if (await fs.stat(path.join(at, ".git")).then(() => true, () => false))
+            return at;
+    }
+    return dir;
+}
 const inside = (root, dir) => dir === root || dir.startsWith(root + path.sep);
 /** `local_address` in /proc/net/tcp{,6}: hex address in little-endian 32-bit words. */
 export function listenPort(line) {
@@ -73,7 +101,7 @@ async function scanProc(root) {
             return;
         const argv = (await fs.readFile(`/proc/${pid}/cmdline`, "utf8").catch(() => "")).split("\0").filter(Boolean);
         for (const port of ports)
-            offers.push({ port, pid: Number(pid), command: commandLabel(argv) });
+            offers.push({ port, pid: Number(pid), command: commandLabel(argv), cwd });
     }));
     return offers;
 }
@@ -103,7 +131,7 @@ async function scanLsof(root) {
         for (const name of values) {
             const match = /^(\*|127\.[\d.]+|\[::1\]|\[::\]|localhost):(\d+)$/.exec(name);
             if (match)
-                offers.push({ port: Number(match[2]), pid, command: commandLabel(args.split(/\s+/)) });
+                offers.push({ port: Number(match[2]), pid, command: commandLabel(args.split(/\s+/)), cwd });
         }
     }
     return offers;

package/dist/apps/service.js

@@ -6,7 +6,7 @@ import { PIN_CHANGE, REVIEW_MODES, regionChange, shouldReview, visualChange } fr
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { scanListeners } from "./listeners.js";
+import { scanListeners, scanMachineListeners } from "./listeners.js";
 import { takeShots } from "./screenshot.js";
 import { approximate, composite, crop, noteAnchor, readNotes, readStrokes, readElementScrolls } from "./annotate.js";
 import { captureFrame, encodePng, sendInput } from "./rfb.js";
@@ -44,6 +44,7 @@ export class AppService {
     terminalStarts = new Map();
     servers = new Map();
     scan;
+    scanMachine;
     serverWatchMs;
     screenshots;
     displays;
@@ -68,6 +69,7 @@ export class AppService {
         this.gateway = gateway;
         this.terminals = terminals;
         this.scan = options.scan ?? scanListeners;
+        this.scanMachine = options.scanMachine ?? scanMachineListeners;
         this.serverWatchMs = options.serverWatchMs ?? 5_000;
         this.screenshots = { enabled: options.screenshots?.enabled ?? (() => false), take: options.screenshots?.take ?? takeShots };
         this.displays = options.displays ?? NO_DISPLAYS;
@@ -330,6 +332,11 @@ export class AppService {
         const claimed = this.registry.claimedPorts(sessionId);
         return { offers: (await this.scan(workspace)).filter((offer) => !claimed.has(offer.port)) };
     }
+    /** Servers running anywhere under `root`, with their projects: what a first
+     *  session can start in and preview before it has a workspace of its own. */
+    async machineOffers(root) {
+        return { offers: await this.scanMachine(root) };
+    }
     /** Publish a detected server. Re-scanned so a client can't adopt an arbitrary port. */
     async adopt(sessionId, workspace, port) {
         const offer = (await this.offers(sessionId, workspace)).offers.find((item) => item.port === port);

package/dist/apps/styles.css

@@ -116,6 +116,7 @@ input, textarea, select { font-family: inherit; font-size: 16px; }
   padding: 9px var(--space-3); border: 0; border-radius: var(--radius-sm);
   background: transparent; color: var(--ink); font: inherit;
   font-size: var(--text-sm); text-align: left; cursor: pointer;
+  text-decoration: none; /* a menu item can be a link to another machine */
 }
 .menu-item:hover, .menu-item[aria-checked="true"], .menu-item.active { background: var(--surface-2); }
 .menu-item.danger { color: var(--danger); }
@@ -3288,6 +3289,9 @@ p.setup-note .btn.link { min-height: 44px; margin-block: calc((1lh - 44px) / 2);
 .readiness .card-title { margin: 0 0 var(--space-1); }
 .readiness .card-sub { margin: 0; }
 .get-started-actions { display: flex; align-items: center; flex-wrap: wrap; gap: var(--space-2) var(--space-3); margin-top: var(--space-3); }
+.get-started-scan { display: flex; align-items: center; gap: var(--space-2); }
+.get-started-app { margin: var(--space-1) 0 0; overflow-wrap: anywhere; }
+.get-started-more { display: flex; align-items: center; flex-wrap: wrap; gap: var(--space-1) var(--space-2); margin-top: var(--space-2); }
 .readiness-checks { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 4px; }
 /* Summarize completed checks so the next setup action stays visible. */
 .readiness-check.state-passed { display: none; }

package/dist/auth.js

@@ -115,10 +115,24 @@ export function isLoopbackAddress(address) {
 // Sockets accepted by a listener that fronts remote callers through a local
 // proxy (`tailscale serve` forwards tailnet traffic from 127.0.0.1). Their peer
 // address is loopback, but the caller is not, so they never get loopback trust.
-const remoteSockets = new WeakSet();
+const remoteSockets = new WeakMap();
 /** Treat every connection `server` accepts as remote, whatever its peer address. */
-export function markRemoteListener(server) {
-    server.on("connection", (socket) => remoteSockets.add(socket));
+export function markRemoteListener(server, options = {}) {
+    server.on("connection", (socket) => remoteSockets.set(socket, options));
+}
+/**
+ * `tailnet:<login>` when a request reached a remote listener from a device
+ * signed in to the tailnet as the machine's owner. The listener binds loopback,
+ * so another local account could forge the header; honor it only where local
+ * callers are trusted anyway (the same rule as the loopback bypass).
+ */
+function tailnetDevice(req) {
+    const options = req.socket ? remoteSockets.get(req.socket) : undefined;
+    const owner = options?.trustedLogin?.()?.toLowerCase();
+    const login = req.headers["tailscale-user-login"];
+    if (!owner || typeof login !== "string" || login.toLowerCase() !== owner)
+        return null;
+    return loopbackAllowed() ? `tailnet:${owner}` : null;
 }
 /** True when a request physically arrived over loopback from a local caller. */
 export function isLoopbackRequest(req) {
@@ -154,7 +168,7 @@ export function tokenFromRequest(req) {
  * `isAuthorized` is off. */
 export function resolveAuth(identity, req) {
     const loopback = isLoopbackRequest(req);
-    const deviceId = identity.verifyToken(tokenFromRequest(req));
+    const deviceId = identity.verifyToken(tokenFromRequest(req)) ?? tailnetDevice(req);
     return { deviceId, loopback };
 }
 export function isAuthorized(ctx) {

package/dist/controllers/app-commands.js

@@ -1,4 +1,8 @@
-export function createAppCommands(service, workspaceFor, published = () => { }) {
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import os from "node:os";
+/** `machineRoot`: where servers are looked for before a session exists (the owner's home). */
+export function createAppCommands(service, workspaceFor, published = () => { }, machineRoot = os.homedir) {
     const workspaceOf = (sessionId) => {
         const workspace = workspaceFor(sessionId);
         if (!workspace)
@@ -13,7 +17,8 @@ export function createAppCommands(service, workspaceFor, published = () => { })
             published(app);
             return { app };
         },
-        "apps.offers": (msg) => service.offers(String(msg.sessionId), workspaceOf(String(msg.sessionId))),
+        // Without a session: servers anywhere in the owner's home, for a first session to open.
+        "apps.offers": (msg) => typeof msg.sessionId === "string" ? service.offers(msg.sessionId, workspaceOf(msg.sessionId)) : service.machineOffers(machineRoot()),
         "apps.adopt": async (msg) => {
             const sessionId = String(msg.sessionId);
             const app = await service.adopt(sessionId, workspaceOf(sessionId), Number(msg.port));

package/dist/protocol/client-command-routes.js

@@ -5,6 +5,8 @@
 export const CLIENT_COMMAND_ROUTES = [
     ...["list", "publish", "offers", "adopt", "open", "logs", "shot", "input", "menu", "present", "showMe", "mute", "reviewMode", "annotate", "clearNotes", "agentNotes", "notes", "share", "unshare", "revoke", "remove"].map((action) => ({ method: "post", path: `/api/apps/${action}`, kind: `apps.${action}` })),
     { method: "post", path: "/api/artifacts/list", kind: "artifacts.list" },
+    { method: "post", path: "/api/access/get", kind: "access.get" },
+    { method: "post", path: "/api/tailnet/machines", kind: "tailnet.machines" },
     { method: "post", path: "/api/auth/credentials/native-preview", kind: "credentials.native.preview" },
     { method: "post", path: "/api/auth/credentials/native-import", kind: "credentials.native.import" },
     { method: "post", path: "/api/session/pause", kind: "session.pause" },

package/dist/protocol/client-command-schemas.js

@@ -11,9 +11,11 @@ export const CLIENT_COMMAND_SCHEMAS = {
     ping: Type.Object(request),
     "apps.list": Type.Object({ ...request, ...optionalSession }),
     "artifacts.list": Type.Object(request),
+    "access.get": Type.Object(request),
+    "tailnet.machines": Type.Object(request),
     "session.fork.local": Type.Object({ ...request, ...session, model: Type.Optional(Type.Object({ provider: Type.Optional(Type.String({ maxLength: 200 })), id: Type.String({ maxLength: 200 }) })) }),
     "apps.publish": Type.Object({ ...request, ...session, manifest: Type.Unknown() }),
-    "apps.offers": Type.Object({ ...request, ...session }),
+    "apps.offers": Type.Object({ ...request, ...optionalSession }),
     "apps.adopt": Type.Object({ ...request, ...session, port: Type.Integer({ minimum: 1024, maximum: 65535 }) }),
     "apps.open": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String(), returnTo: Type.Optional(Type.String({ maxLength: 2048 })), direct: Type.Optional(Type.Boolean()), scale: Type.Optional(Type.Integer({ minimum: 1, maximum: 2 })), path: Type.Optional(Type.String({ maxLength: 2048 })) }),
     "apps.shot": Type.Object({ ...request, ...session, appId: Type.Optional(Type.String()), widths: Type.Optional(Type.Array(Type.Integer(), { maxItems: 4 })), themes: Type.Optional(Type.Array(Type.Union([Type.Literal("light"), Type.Literal("dark")]), { maxItems: 2 })), path: Type.Optional(Type.String({ maxLength: 2048 })) }),

package/dist/remote/direct.js

@@ -15,7 +15,8 @@ export function loadDirectListenerConfig(appDir) {
         const port = Number(raw.port);
         if (!Number.isInteger(port) || port <= 0 || port > 65535)
             return null;
-        return { port, hostname: typeof raw.hostname === "string" && raw.hostname ? raw.hostname : undefined };
+        const text = (value) => (typeof value === "string" && value ? value : undefined);
+        return { port, hostname: text(raw.hostname), owner: text(raw.owner) };
     }
     catch {
         return null;

package/dist/remote/index.js

@@ -13,3 +13,4 @@
 export { RelayConnector, loadRelayConfig } from "./relay-client.js";
 export { soloCredentials, buildDialUrl } from "./solo.js";
 export { loadDirectListenerConfig, DIRECT_CONFIG_FILE } from "./direct.js";
+export { discoverTailnetMachines, parseTailnetPeers } from "./tailnet.js";