symbio 0.2.0 → 0.3.0-beta.1

package/CHANGELOG.md

@@ -5,6 +5,17 @@ versions follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.0]
+
+- Remote access: `sym remote` (or Settings → Remote access) opens a temporary Cloudflare link with an
+  8-character access code; remote sessions need the code, 10 wrong codes shut it down, the agents'
+  tools and shutdown are never reachable through it, and a banner with a Turn off button shows it's on.
+
+## [0.2.1]
+
+- Releases are published from GitHub Actions with npm trusted publishing (no tokens), with
+  provenance.
+
 ## [0.2.0]
 
 - Installable with `npm install -g symbio`; brings its own OpenCode (pinned to 2.1.x).

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 LinKzy
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 LinKzy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -112,6 +112,13 @@ on your computer, including the agents, from using Symbio's API behind your back
 | `sym logs` | The last lines of the log (`~/.symbio/logs/symbio.log`). |
 | `sym doctor` | Check Node.js, git, OpenCode, the port and model providers. |
 | `sym run` | Run in the foreground, with the log in the terminal. |
+| `sym remote` | Open a temporary link and access code to use Symbio from another device (see below). `sym remote off` closes it. |
+
+**From another device.** `sym remote` opens a temporary Cloudflare link to your Symbio and prints it
+with an access code. Open the link anywhere (phone, another computer), enter the code, and you're
+in. A banner shows it's on, with a button to turn it off; after 10 wrong codes it turns off by
+itself. Whoever gets in controls your agents, so keep the link and code to yourself. Details in
+[docs/security.md](docs/security.md#remote-access-optional).
 
 `symbio` works too, as the long name of `sym`. To run from a clone instead: `npm install`,
 `npm run build`, then `npm link` once to get the commands.
@@ -172,6 +179,7 @@ All optional, set as environment variables:
 | `SYMBIO_NO_OPEN` | | Set to `1` to not open the browser on start (use the link Symbio prints) |
 | `SYMBIO_DEBUG` | | Set to `1` to enable the read-only OpenCode debug routes (for development) |
 | `SYMBIO_OPENCODE_BIN` | bundled | Path to an `opencode` executable to use instead of the bundled one |
+| `SYMBIO_CLOUDFLARED_BIN` | auto | Path to `cloudflared` for remote access (otherwise the PATH, or a copy downloaded once) |
 | `SYMBIO_STUCK_MINUTES` | `10` | Silence before the watchdog interrupts a working agent |
 | `SYMBIO_RECYCLE_MB` | `1500` | Restart OpenCode above this memory use once every agent is idle |
 | `SYMBIO_RECYCLE_HARD_MB` | `3000` | Restart OpenCode above this memory use regardless (agents resume) |

package/bin/symbio.js

@@ -8,6 +8,7 @@
 //   sym logs       the last lines of its log
 //   sym doctor     check that everything Symbio needs is in place
 //   sym run        run in the foreground (for debugging)
+//   sym remote     open a temporary link to use Symbio from another device (sym remote off to close it)
 
 import { execFileSync, exec, spawn } from "node:child_process";
 import { existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
@@ -113,12 +114,43 @@ async function status() {
   const runtime = (await api("GET", "/api/runtime")).body;
   const projects = (await api("GET", "/api/projects")).body ?? [];
   console.log(`OpenCode ${runtime?.version ?? "?"} (${runtime?.state ?? "?"}${runtime?.memoryMB ? `, ${runtime.memoryMB} MB` : ""})`);
+  const remote = (await api("GET", "/api/remote")).body;
+  if (remote?.active) console.log(`Remote access ON: ${remote.url} (${remote.sessions} session(s)) — sym remote off`);
   for (const p of projects) {
     const working = p.agents.filter((a) => a.status === "busy").length;
     console.log(`- ${p.name}: ${p.agents.filter((a) => a.status !== "stopped").length} agents${working ? `, ${working} working` : ""}${p.paused ? " (paused)" : ""}`);
   }
 }
 
+async function remoteOn() {
+  if ((await state()) !== "running") {
+    process.env.SYMBIO_NO_OPEN = "1";
+    await start();
+  }
+  console.log("Opening a temporary link (the first time, cloudflared is downloaded)…");
+  const res = await fetch(BASE + "/api/remote/start", { method: "POST", headers: { "x-symbio-token": token() }, signal: AbortSignal.timeout(180_000) });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    console.error(`Couldn't open remote access: ${body.error ?? res.status}`);
+    process.exit(1);
+  }
+  const code = body.code ? `${body.code.slice(0, 4)}-${body.code.slice(4)}` : "?";
+  console.log(`
+Remote access is on.
+
+  Link: ${body.url}
+  Code: ${code}
+
+Whoever has both controls your agents, which run commands on this computer.
+Turn it off with "sym remote off" (or the button in Symbio). After 10 wrong codes it turns off by itself.`);
+}
+
+async function remoteOff() {
+  if ((await state()) !== "running") return console.log("Symbio isn't running.");
+  await api("POST", "/api/remote/stop");
+  console.log("Remote access is off.");
+}
+
 function logs() {
   if (!existsSync(LOG)) return console.log(`No log yet (${LOG}).`);
   const lines = readFileSync(LOG, "utf8").split(/\r?\n/);
@@ -169,6 +201,8 @@ Usage: sym [command]
   logs            show the last lines of the log
   doctor          check that everything Symbio needs is in place
   run             run in the foreground (logs in this terminal)
+  remote          open a temporary link + access code to use Symbio from another device
+  remote off      close that link
   --version       print the version
 
 Environment: SYMBIO_PORT (default 4310), SYMBIO_HOME (default ~/.symbio), SYMBIO_NO_OPEN=1.`);
@@ -191,6 +225,11 @@ switch (cmd) {
       openBrowser(link());
     } else console.log('Symbio isn\'t running. Start it with "sym".');
     break;
+  case "remote":
+  case "--remote":
+    if (process.argv[3] === "off") await remoteOff();
+    else await remoteOn();
+    break;
   case "logs":
     logs();
     break;

package/dist/server/folder-picker.js

@@ -6,76 +6,76 @@ import { execFile } from "node:child_process";
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-const WINDOWS_SCRIPT = String.raw `
-param([string]$Initial = "", [string]$Title = "Choose the project folder")
-$ErrorActionPreference = "Stop"
-[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
-Add-Type -AssemblyName System.Windows.Forms
-Add-Type -ReferencedAssemblies System.Windows.Forms -TypeDefinition @"
-using System;
-using System.Runtime.InteropServices;
-using System.Windows.Forms;
-
-public static class SymbioFolderPicker {
-  [ComImport, Guid("DC1C5A9C-E88A-4dde-A5A1-60F82A20AEF7")] private class FileOpenDialogCom {}
-
-  [ComImport, Guid("42f85136-db7e-439c-85f1-e4075d135fc8"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
-  private interface IFileOpenDialog {
-    [PreserveSig] int Show(IntPtr hwndOwner);
-    void SetFileTypes(); void SetFileTypeIndex(); void GetFileTypeIndex(); void Advise(); void Unadvise();
-    void SetOptions(uint fos);
-    void GetOptions(out uint fos);
-    void SetDefaultFolder(IShellItem psi);
-    void SetFolder(IShellItem psi);
-    void GetFolder(); void GetCurrentSelection(); void SetFileName(); void GetFileName();
-    void SetTitle([MarshalAs(UnmanagedType.LPWStr)] string pszTitle);
-    void SetOkButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string pszText);
-    void SetFileNameLabel();
-    void GetResult(out IShellItem ppsi);
-  }
-
-  [ComImport, Guid("43826d1e-e718-42ee-bc55-a1e261c37bfe"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
-  private interface IShellItem {
-    void BindToHandler(); void GetParent();
-    void GetDisplayName(uint sigdnName, [MarshalAs(UnmanagedType.LPWStr)] out string ppszName);
-    void GetAttributes(); void Compare();
-  }
-
-  [DllImport("shell32.dll", CharSet = CharSet.Unicode, PreserveSig = false)]
-  private static extern void SHCreateItemFromParsingName(string pszPath, IntPtr pbc, [MarshalAs(UnmanagedType.LPStruct)] Guid riid, out IShellItem ppv);
-
-  public static string Pick(string initial, string title) {
-    // An invisible topmost window owns the dialog so it opens in front of the browser.
-    var owner = new Form { ShowInTaskbar = false, TopMost = true, FormBorderStyle = FormBorderStyle.None, Opacity = 0, Width = 1, Height = 1, StartPosition = FormStartPosition.CenterScreen };
-    owner.Show();
-    owner.Activate();
-    try {
-      var dialog = (IFileOpenDialog)new FileOpenDialogCom();
-      dialog.SetOptions(0x20 | 0x40 | 0x800); // PICKFOLDERS | FORCEFILESYSTEM | PATHMUSTEXIST
-      dialog.SetTitle(title);
-      dialog.SetOkButtonLabel("Select folder");
-      if (!String.IsNullOrEmpty(initial)) {
-        try {
-          IShellItem folder;
-          SHCreateItemFromParsingName(initial, IntPtr.Zero, typeof(IShellItem).GUID, out folder);
-          dialog.SetFolder(folder);
-        } catch { }
-      }
-      int hr = dialog.Show(owner.Handle);
-      if (hr != 0) return null; // cancelled
-      IShellItem result;
-      dialog.GetResult(out result);
-      string p;
-      result.GetDisplayName(0x80058000, out p); // SIGDN_FILESYSPATH
-      return p;
-    } finally {
-      owner.Close();
-    }
-  }
-}
-"@
-$picked = [SymbioFolderPicker]::Pick($Initial, $Title)
-if ($picked) { [Console]::Out.Write($picked) }
+const WINDOWS_SCRIPT = String.raw `
+param([string]$Initial = "", [string]$Title = "Choose the project folder")
+$ErrorActionPreference = "Stop"
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -ReferencedAssemblies System.Windows.Forms -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+using System.Windows.Forms;
+
+public static class SymbioFolderPicker {
+  [ComImport, Guid("DC1C5A9C-E88A-4dde-A5A1-60F82A20AEF7")] private class FileOpenDialogCom {}
+
+  [ComImport, Guid("42f85136-db7e-439c-85f1-e4075d135fc8"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  private interface IFileOpenDialog {
+    [PreserveSig] int Show(IntPtr hwndOwner);
+    void SetFileTypes(); void SetFileTypeIndex(); void GetFileTypeIndex(); void Advise(); void Unadvise();
+    void SetOptions(uint fos);
+    void GetOptions(out uint fos);
+    void SetDefaultFolder(IShellItem psi);
+    void SetFolder(IShellItem psi);
+    void GetFolder(); void GetCurrentSelection(); void SetFileName(); void GetFileName();
+    void SetTitle([MarshalAs(UnmanagedType.LPWStr)] string pszTitle);
+    void SetOkButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string pszText);
+    void SetFileNameLabel();
+    void GetResult(out IShellItem ppsi);
+  }
+
+  [ComImport, Guid("43826d1e-e718-42ee-bc55-a1e261c37bfe"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  private interface IShellItem {
+    void BindToHandler(); void GetParent();
+    void GetDisplayName(uint sigdnName, [MarshalAs(UnmanagedType.LPWStr)] out string ppszName);
+    void GetAttributes(); void Compare();
+  }
+
+  [DllImport("shell32.dll", CharSet = CharSet.Unicode, PreserveSig = false)]
+  private static extern void SHCreateItemFromParsingName(string pszPath, IntPtr pbc, [MarshalAs(UnmanagedType.LPStruct)] Guid riid, out IShellItem ppv);
+
+  public static string Pick(string initial, string title) {
+    // An invisible topmost window owns the dialog so it opens in front of the browser.
+    var owner = new Form { ShowInTaskbar = false, TopMost = true, FormBorderStyle = FormBorderStyle.None, Opacity = 0, Width = 1, Height = 1, StartPosition = FormStartPosition.CenterScreen };
+    owner.Show();
+    owner.Activate();
+    try {
+      var dialog = (IFileOpenDialog)new FileOpenDialogCom();
+      dialog.SetOptions(0x20 | 0x40 | 0x800); // PICKFOLDERS | FORCEFILESYSTEM | PATHMUSTEXIST
+      dialog.SetTitle(title);
+      dialog.SetOkButtonLabel("Select folder");
+      if (!String.IsNullOrEmpty(initial)) {
+        try {
+          IShellItem folder;
+          SHCreateItemFromParsingName(initial, IntPtr.Zero, typeof(IShellItem).GUID, out folder);
+          dialog.SetFolder(folder);
+        } catch { }
+      }
+      int hr = dialog.Show(owner.Handle);
+      if (hr != 0) return null; // cancelled
+      IShellItem result;
+      dialog.GetResult(out result);
+      string p;
+      result.GetDisplayName(0x80058000, out p); // SIGDN_FILESYSPATH
+      return p;
+    } finally {
+      owner.Close();
+    }
+  }
+}
+"@
+$picked = [SymbioFolderPicker]::Pick($Initial, $Title)
+if ($picked) { [Console]::Out.Write($picked) }
 `;
 let busy = false;
 /** Opens the native folder dialog. Resolves to the chosen path, or null if cancelled. */

package/dist/server/index.js

@@ -10,6 +10,8 @@ import { RemoteOps } from "./remote.js";
 import { handleMcp } from "./mcp.js";
 import { isAllowedRequest } from "./origin.js";
 import { loadUiToken, tokenMatches } from "./ui-token.js";
+import { isTunnelRequest, loginPage, RemoteAccess, remoteDecision, SESSION_COOKIE } from "./remote-access.js";
+import { bus } from "./bus.js";
 import { OpencodeRuntime } from "./opencode/runtime.js";
 import { Store, globalDir } from "./store.js";
 import { Team } from "./team.js";
@@ -66,11 +68,42 @@ async function main() {
     // are told to continue once OpenCode is up again.
     team.markInterrupted("Symbio was stopped and has been restarted");
     const uiToken = loadUiToken(globalDir);
+    const remote = new RemoteAccess(path.join(globalDir, "bin"));
+    remote.onChange = () => bus.publish({ type: "remote.updated" });
+    const remoteRequests = new WeakSet(); // requests that came through the tunnel
     const app = new Hono();
     app.use("*", async (c, next) => {
-        const ok = isAllowedRequest({ method: c.req.method, host: c.req.header("host"), origin: c.req.header("origin") }, PORT);
-        if (!ok)
-            return c.json({ error: "Requests must come from Symbio's own page on this computer." }, 403);
+        const viaTunnel = isTunnelRequest({ host: c.req.header("host"), cfRay: c.req.header("cf-ray"), cfIp: c.req.header("cf-connecting-ip") }, remote.host);
+        if (!viaTunnel) {
+            const ok = isAllowedRequest({ method: c.req.method, host: c.req.header("host"), origin: c.req.header("origin") }, PORT);
+            if (!ok)
+                return c.json({ error: "Requests must come from Symbio's own page on this computer." }, 403);
+            return next();
+        }
+        // Through the tunnel: only Symbio's own remote page may change things.
+        const origin = c.req.header("origin");
+        if (c.req.method !== "GET" && c.req.method !== "HEAD" && origin && origin !== `https://${remote.host}`) {
+            return c.json({ error: "Not allowed." }, 403);
+        }
+        const decision = remoteDecision({ method: c.req.method, path: c.req.path, hasSession: remote.hasSession(c.req.header("cookie")), active: remote.active });
+        if (decision === "deny")
+            return c.text("Not available through remote access.", 403);
+        if (decision === "login-page")
+            return c.html(loginPage());
+        if (decision === "need-login")
+            return c.json({ error: "Log in with the access code.", code: "remote-login" }, 401);
+        if (decision === "login-submit") {
+            const body = await c.req.json().catch(() => ({}));
+            const result = await remote.login(String(body.code ?? ""));
+            if (result.ok) {
+                c.header("Set-Cookie", `${SESSION_COOKIE}=${result.session}; Path=/; Max-Age=${result.maxAge}; HttpOnly; Secure; SameSite=Strict`);
+                return c.json({ token: uiToken });
+            }
+            if (!remote.active)
+                return c.json({ error: "Too many wrong codes: remote access was turned off." }, 423);
+            return c.json({ error: `Wrong code. ${result.left} attempt${result.left === 1 ? "" : "s"} left.` }, 401);
+        }
+        remoteRequests.add(c.req.raw);
         await next();
     });
     // The UI's key: a header, or a query parameter for the event stream (EventSource can't set headers).
@@ -87,6 +120,20 @@ async function main() {
         setTimeout(() => void shutdown?.(), 200);
         return c.json({ ok: true });
     });
+    // Remote access: status for everyone (the code only locally), start locally, stop from anywhere.
+    app.get("/api/remote", (c) => c.json(remote.status(!remoteRequests.has(c.req.raw))));
+    app.post("/api/remote/start", async (c) => {
+        try {
+            return c.json(await remote.start(PORT));
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 500);
+        }
+    });
+    app.post("/api/remote/stop", (c) => {
+        remote.stop(remoteRequests.has(c.req.raw) ? "turned off from a remote session" : "turned off on this computer");
+        return c.json(remote.status(!remoteRequests.has(c.req.raw)));
+    });
     app.route("/api", createApi(store, runtime, team, connections));
     // Agents' tool server. Only reachable from this machine (we bind to 127.0.0.1) and only with a per-run token.
     app.all("/mcp/:token", (c) => handleMcp(c, team.mcpResolver));
@@ -115,6 +162,7 @@ async function main() {
         .catch((err) => console.error("OpenCode failed to start:", err.message));
     team.startWatchdog();
     shutdown = async () => {
+        remote.stop("Symbio stopped");
         team.shuttingDown = true;
         team.stopWatchdog();
         await runtime.stop();

package/dist/server/remote-access.js

@@ -0,0 +1,270 @@
+// Remote access: a temporary Cloudflare quick tunnel (https://….trycloudflare.com) to this
+// Symbio, guarded by an access code.
+//
+// Through the tunnel Symbio controls agents that run commands on this computer, so:
+// - remote requests need a session, obtained by entering the access code (8 characters);
+//   after 10 wrong codes the tunnel is shut down;
+// - API calls also need the UI key, as locally (a leaked key alone isn't enough from outside);
+// - the agents' tool endpoint, debug routes and shutdown are never reachable remotely;
+// - turning remote access off ends every remote session; the code is shown only locally.
+import { spawn, spawnSync } from "node:child_process";
+import { randomBytes, randomInt, timingSafeEqual } from "node:crypto";
+import { chmodSync, existsSync, promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"; // no 0/O, 1/I/L
+export const CODE_LENGTH = 8;
+export const MAX_FAILURES = 10;
+const SESSION_MS = 12 * 3600_000;
+export const SESSION_COOKIE = "symbio_remote";
+export function newAccessCode() {
+    let code = "";
+    for (let i = 0; i < CODE_LENGTH; i++)
+        code += CODE_ALPHABET[randomInt(CODE_ALPHABET.length)];
+    return code;
+}
+export function codesMatch(expected, given) {
+    const a = Buffer.from(expected);
+    const b = Buffer.from(given.trim().toUpperCase().replace(/[\s-]/g, ""));
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** Requests that came through Cloudflare (they carry its headers) or name the tunnel's host. */
+export function isTunnelRequest(headers, tunnelHost) {
+    if (headers.cfRay || headers.cfIp)
+        return true;
+    const host = (headers.host ?? "").replace(/:\d+$/, "").toLowerCase();
+    return !!tunnelHost && host === tunnelHost.toLowerCase();
+}
+// Never through the tunnel: the agents' tools, debugging, shutting Symbio down, starting a
+// tunnel, and the native folder dialog (it would open on this computer's screen).
+const NEVER_REMOTE = [/^\/mcp(\/|$)/, /^\/api\/debug(\/|$)/, /^\/api\/shutdown$/, /^\/api\/remote\/start$/, /^\/api\/pick-folder$/];
+/** What to do with a request that came through the tunnel. */
+export function remoteDecision(req) {
+    if (!req.active)
+        return "deny";
+    if (NEVER_REMOTE.some((re) => re.test(req.path)))
+        return "deny";
+    if (req.path === "/remote-login")
+        return req.method === "POST" ? "login-submit" : "login-page";
+    if (req.hasSession)
+        return "allow";
+    return req.path.startsWith("/api/") ? "need-login" : "login-page";
+}
+export function cookieValue(header, name) {
+    for (const part of (header ?? "").split(";")) {
+        const [k, ...v] = part.trim().split("=");
+        if (k === name)
+            return v.join("=");
+    }
+    return null;
+}
+export class RemoteAccess {
+    binDir;
+    proc = null;
+    url = null;
+    code = null;
+    startedAt = null;
+    sessions = new Map(); // id → expiry
+    failures = 0;
+    lastStop = null;
+    onChange = () => { };
+    constructor(binDir) {
+        this.binDir = binDir;
+    }
+    get active() {
+        return !!this.proc && !!this.url;
+    }
+    get host() {
+        return this.url ? new URL(this.url).host : null;
+    }
+    status(local) {
+        this.pruneSessions();
+        return {
+            active: this.active,
+            url: this.url,
+            startedAt: this.startedAt,
+            sessions: this.sessions.size,
+            ...(local ? { code: this.code } : {}),
+            lastStop: this.lastStop,
+        };
+    }
+    /** Opens the tunnel to http://127.0.0.1:<port>. Resolves once Cloudflare gave a URL. */
+    async start(port) {
+        if (this.active)
+            return this.status(true);
+        const bin = await this.cloudflared();
+        const args = ["tunnel", "--no-autoupdate", "--url", `http://127.0.0.1:${port}`];
+        // A .js stand-in (SYMBIO_CLOUDFLARED_BIN) runs with Node: used to test without opening a real tunnel.
+        const [cmd, argv] = /\.m?js$/.test(bin) ? [process.execPath, [bin, ...args]] : [bin, args];
+        const proc = spawn(cmd, argv, { windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+        this.proc = proc;
+        const url = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error("Cloudflare didn't open a tunnel within 60 seconds.")), 60_000);
+            const onData = (buf) => {
+                const m = buf.toString().match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/);
+                if (m) {
+                    clearTimeout(timer);
+                    resolve(m[0]);
+                }
+            };
+            proc.stdout.on("data", onData);
+            proc.stderr.on("data", onData);
+            proc.once("exit", (code) => {
+                clearTimeout(timer);
+                reject(new Error(`cloudflared exited (code ${code}) before opening the tunnel.`));
+            });
+        }).catch((err) => {
+            this.kill();
+            throw err;
+        });
+        this.url = url;
+        this.code = newAccessCode();
+        this.startedAt = Date.now();
+        this.failures = 0;
+        this.sessions.clear();
+        proc.once("exit", () => {
+            if (this.proc === proc)
+                this.reset("the tunnel closed");
+        });
+        console.log(`[remote] on: ${url}`);
+        this.onChange();
+        return this.status(true);
+    }
+    stop(reason) {
+        if (!this.proc && !this.url)
+            return;
+        this.kill();
+        this.reset(reason);
+    }
+    kill() {
+        const proc = this.proc;
+        this.proc = null;
+        if (proc && proc.exitCode === null)
+            proc.kill();
+    }
+    reset(reason) {
+        this.proc = null;
+        this.url = null;
+        this.code = null;
+        this.startedAt = null;
+        this.sessions.clear();
+        this.lastStop = { at: Date.now(), reason };
+        console.log(`[remote] off: ${reason}`);
+        this.onChange();
+    }
+    hasSession(cookieHeader) {
+        const id = cookieValue(cookieHeader, SESSION_COOKIE);
+        const expiry = id ? this.sessions.get(id) : undefined;
+        return !!expiry && expiry > Date.now();
+    }
+    /** Checks an access code. Too many wrong ones shut the tunnel down. */
+    async login(given) {
+        if (this.code && codesMatch(this.code, given)) {
+            const session = randomBytes(32).toString("base64url");
+            this.sessions.set(session, Date.now() + SESSION_MS);
+            console.log("[remote] a remote session started");
+            this.onChange();
+            return { ok: true, session, maxAge: SESSION_MS / 1000 };
+        }
+        this.failures++;
+        console.warn(`[remote] wrong access code (${this.failures}/${MAX_FAILURES})`);
+        if (this.failures >= MAX_FAILURES)
+            this.stop(`${MAX_FAILURES} wrong access codes; turned off for safety`);
+        await new Promise((r) => setTimeout(r, 1500)); // slows guessing down
+        return { ok: false, left: Math.max(0, MAX_FAILURES - this.failures) };
+    }
+    pruneSessions() {
+        const now = Date.now();
+        for (const [id, exp] of this.sessions)
+            if (exp <= now)
+                this.sessions.delete(id);
+    }
+    /** cloudflared from SYMBIO_CLOUDFLARED_BIN, the PATH, or downloaded once into ~/.symbio/bin. */
+    async cloudflared() {
+        if (process.env.SYMBIO_CLOUDFLARED_BIN)
+            return process.env.SYMBIO_CLOUDFLARED_BIN;
+        const onPath = spawnSync("cloudflared", ["--version"], { windowsHide: true, encoding: "utf8" });
+        if (onPath.status === 0)
+            return "cloudflared";
+        const exe = path.join(this.binDir, process.platform === "win32" ? "cloudflared.exe" : "cloudflared");
+        if (existsSync(exe))
+            return exe;
+        await downloadCloudflared(exe);
+        return exe;
+    }
+}
+/** Downloads cloudflared from Cloudflare's official GitHub releases. */
+async function downloadCloudflared(dest) {
+    const arch = os.arch() === "arm64" ? "arm64" : "amd64";
+    const asset = process.platform === "win32"
+        ? `cloudflared-windows-${arch}.exe`
+        : process.platform === "darwin"
+            ? `cloudflared-darwin-${arch}.tgz`
+            : `cloudflared-linux-${arch}`;
+    const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/${asset}`;
+    console.log(`[remote] downloading cloudflared (${asset})…`);
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`Couldn't download cloudflared (${res.status}). Install it yourself: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/`);
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    const tmp = `${dest}.download`;
+    await fs.writeFile(tmp, Buffer.from(await res.arrayBuffer()));
+    if (asset.endsWith(".tgz")) {
+        const r = spawnSync("tar", ["-xzf", tmp, "-C", path.dirname(dest)]);
+        await fs.rm(tmp, { force: true });
+        if (r.status !== 0)
+            throw new Error("Couldn't unpack cloudflared.");
+    }
+    else {
+        await fs.rename(tmp, dest);
+    }
+    if (process.platform !== "win32")
+        chmodSync(dest, 0o755);
+}
+/** The page remote visitors see first: enter the access code. Self-contained (no assets). */
+export function loginPage() {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex" />
+<title>Symbio — remote access</title>
+<style>
+  :root { color-scheme: dark; }
+  body { margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center; background: #0b0c0e; color: #e8e9ec; font: 14px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+  .card { width: min(360px, calc(100vw - 32px)); padding: 28px 24px; border: 1px solid #23252b; border-radius: 12px; background: #111215; }
+  h1 { margin: 0 0 6px; font-size: 18px; display: flex; align-items: center; gap: 8px; }
+  p { margin: 0 0 18px; color: #9a9ca4; }
+  input { box-sizing: border-box; width: 100%; height: 44px; padding: 0 12px; border-radius: 8px; border: 1px solid #2c2f36; background: #0b0c0e; color: #e8e9ec; font: 600 20px/1 ui-monospace, monospace; letter-spacing: 0.25em; text-transform: uppercase; text-align: center; }
+  input:focus { outline: none; border-color: #6d6af5; box-shadow: 0 0 0 3px rgba(109,106,245,.25); }
+  button { margin-top: 12px; width: 100%; height: 40px; border: 0; border-radius: 8px; background: #6d6af5; color: white; font: 600 14px system-ui, sans-serif; cursor: pointer; }
+  button:disabled { opacity: .6; cursor: default; }
+  .error { margin-top: 12px; color: #f0726a; min-height: 1.5em; }
+</style>
+</head>
+<body>
+<form class="card" id="f">
+  <h1><svg width="22" height="22" viewBox="0 0 24 24"><circle cx="9" cy="12" r="6.5" fill="none" stroke="#6d6af5" stroke-width="2.2"/><circle cx="15" cy="12" r="6.5" fill="none" stroke="#3fb27f" stroke-width="2.2"/></svg>Symbio</h1>
+  <p>Enter the access code shown on the computer running Symbio.</p>
+  <input id="code" name="code" autocomplete="one-time-code" maxlength="12" autofocus required />
+  <button id="go">Open Symbio</button>
+  <div class="error" id="err"></div>
+</form>
+<script>
+  const f = document.getElementById("f"), go = document.getElementById("go"), err = document.getElementById("err");
+  f.addEventListener("submit", async (e) => {
+    e.preventDefault();
+    go.disabled = true; err.textContent = "";
+    try {
+      const res = await fetch("/remote-login", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ code: document.getElementById("code").value }) });
+      const data = await res.json().catch(() => ({}));
+      if (res.ok && data.token) { localStorage.setItem("symbio:token", data.token); location.href = "/"; return; }
+      err.textContent = data.error || "That didn't work.";
+    } catch { err.textContent = "Couldn't reach Symbio."; }
+    go.disabled = false;
+  });
+</script>
+</body>
+</html>`;
+}