ollanet 0.6.23 → 0.7.0

package/README.md

@@ -4,9 +4,7 @@
 
 # ollanet
 
-Find, manage, and use Ollama models on the hosts you choose.
-
-**CLI** for humans · **MCP** for agents · **Node** for apps.
+Find, manage, and use Ollama models on the hosts you choose, from a CLI, an MCP server for agents, or a Node library.
 
 Discover hosts, give models convenient aliases, and prompt or compare them. A reachable host is not a trusted host. LAN scan is opt-in. Node 20+, zero runtime deps.
 
@@ -39,7 +37,7 @@ Host-first: `ollanet <cmd> <machine> …`. The machine is a MagicDNS name, a con
 
 **Manage.** `pull`, `show`, `rm`, and `ps` on a named machine. Comparisons and benches are deeper workflows on [ollanet.dev/docs](https://ollanet.dev/docs).
 
-**Use.** Prompt, continue a chat by hash, or call the same inventory from MCP and the Node library.
+**Use.** Prompt, continue a chat by hash, or call the same inventory from MCP and the Node library. Agents off your network can read a token-gated, read-only model catalog with `ollanet serve` (no hostnames or IPs, no prompt proxying). `-q` keeps stderr for errors only, and `--stdin` reads a piped prompt.
 
 ## Reachability and trust
 
@@ -59,6 +57,7 @@ This package does not include vendor telemetry. Commands still cause network tra
 | `rm` | Delete request (`--yes`) | Remove that model from the host | Model removed on the remote host |
 | `alias` | None to Ollama | None | Local `config.json` |
 | `chats` | None to Ollama | None | Reads local transcripts |
+| `serve` | Tag and metadata probes when it refreshes | Answer with tags and model metadata | Token hashes in `~/.ollanet/serve.json` |
 
 Other machines see a saved chat only if they share the responses directory (or the same `~/.ollanet/` when installed). This table covers the operations inspected in this repo. It does not prove every possible data path is listed.
 
@@ -94,6 +93,8 @@ pnpm test
 pnpm ollanet -- help
 ```
 
+A checkout reads `./config.json` (gitignored, optional). Copy `config.example.json` to start. `config.json` was tracked before 0.7.0: if your checkout has one with your hosts or aliases, copy it somewhere safe before pulling, since the pull removes it (or refuses if you edited it), then put it back.
+
 Site (FilePress + docs mount): `pnpm --dir site ship`
 
 ## License

package/dist/argv.d.ts

@@ -6,6 +6,24 @@ export type UsageFn = () => never;
 export declare function isHelpFlag(arg: string): boolean;
 /** Intentional help: stdout, exit 0. */
 export declare function printHelp(text: string): never;
+/**
+ * Quiet mode (`-q` / `--quiet` on any command, or OLLANET_QUIET=1): results on
+ * stdout only. stderr keeps real errors and warnings (and --think reasoning,
+ * which you asked for); saved paths, hints, notices, and progress are dropped.
+ */
+export declare function isQuiet(): boolean;
+/**
+ * Remove `-q` / `--quiet` from a command's argv and switch quiet mode on.
+ * Done once in the CLI entry so every command accepts it in any position.
+ */
+export declare function takeQuietFlag(argv: string[]): string[];
+/**
+ * Decorative progress lines (`→ model (1/2)`) are for people watching a
+ * terminal. Piped and agent runs skip them so stderr only carries results and
+ * real errors (PowerShell 5 wraps every native stderr line in a red
+ * NativeCommandError). OLLANET_PROGRESS=1 forces them on, 0 forces them off.
+ */
+export declare function showProgress(): boolean;
 /** Usage error: stderr, exit 1. */
 export declare function failUsage(text: string): never;
 export declare function takeValue(args: string[], flag: string, usage: UsageFn): string;

package/dist/argv.js

@@ -6,6 +6,41 @@ export function printHelp(text) {
     process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
     process.exit(0);
 }
+/**
+ * Quiet mode (`-q` / `--quiet` on any command, or OLLANET_QUIET=1): results on
+ * stdout only. stderr keeps real errors and warnings (and --think reasoning,
+ * which you asked for); saved paths, hints, notices, and progress are dropped.
+ */
+export function isQuiet() {
+    const flag = process.env.OLLANET_QUIET?.trim().toLowerCase();
+    return flag === "1" || flag === "true";
+}
+/**
+ * Remove `-q` / `--quiet` from a command's argv and switch quiet mode on.
+ * Done once in the CLI entry so every command accepts it in any position.
+ */
+export function takeQuietFlag(argv) {
+    const rest = argv.filter((arg) => arg !== "-q" && arg !== "--quiet");
+    if (rest.length !== argv.length)
+        process.env.OLLANET_QUIET = "1";
+    return rest;
+}
+/**
+ * Decorative progress lines (`→ model (1/2)`) are for people watching a
+ * terminal. Piped and agent runs skip them so stderr only carries results and
+ * real errors (PowerShell 5 wraps every native stderr line in a red
+ * NativeCommandError). OLLANET_PROGRESS=1 forces them on, 0 forces them off.
+ */
+export function showProgress() {
+    if (isQuiet())
+        return false;
+    const flag = process.env.OLLANET_PROGRESS?.trim().toLowerCase();
+    if (flag === "1" || flag === "true")
+        return true;
+    if (flag === "0" || flag === "false")
+        return false;
+    return Boolean(process.stderr.isTTY);
+}
 /** Usage error: stderr, exit 1. */
 export function failUsage(text) {
     console.error(text);

package/dist/bench.js

@@ -6,7 +6,7 @@ import { comparabilityKey, getSuiteCases, LONG_THROUGHPUT_NUM_PREDICT, median, s
 import { benchmarksDir, newBenchId, saveBenchmark } from "./bench-store.js";
 import { readFile } from "node:fs/promises";
 import { envInt, ollamaBaseUrl, shortName } from "./hosts.js";
-import { consumeSettingsFlag, failUsage, isHelpFlag, parseNumberFlag, printHelp, takeFlag } from "./argv.js";
+import { consumeSettingsFlag, failUsage, isHelpFlag, isQuiet, parseNumberFlag, printHelp, showProgress, takeFlag, } from "./argv.js";
 import { resolveTarget } from "./target.js";
 import { projectPath } from "./paths.js";
 import { contextLengthForModel, isCompletionCapable, isVisionCapable, ollamaChat, ollamaShow, ollamaTags, ollamaUnload, ollamaVersion, ollamaPs, psHasModel, shouldWarnNoThinking, vramForModel, waitUntilUnloaded, } from "./ollama-chat.js";
@@ -43,6 +43,7 @@ Options:
   --judge               Second pass: score check answers 1–5
   --judge-model <name>  Required with --judge (no default)
   --json                Machine-readable stdout
+  -q, --quiet           Table only; no plan, notes, or saved paths on stderr
   --save / --no-save    Persist under benchmarks/ (default on)
   --fail-fast           Stop remaining models after the first hard error
   --fail-on-error       Exit 2 if any model/case errored
@@ -642,7 +643,8 @@ export async function main() {
             const pin = pinnedNumPredict(c, parsed.throughputNumPredict);
             return n + caseReps(c, parsed.runs, parsed.hot) * attemptTimeoutMs(pin);
         }, 0);
-    if (!parsed.json) {
+    const quiet = isQuiet();
+    if (!parsed.json && !quiet) {
         const skipBits = [
             skipped.filter((s) => s.reason === "non-completion").length
                 ? `${skipped.filter((s) => s.reason === "non-completion").length} embedding/other`
@@ -669,7 +671,7 @@ export async function main() {
         }
         console.error("Proceeding…");
     }
-    if (parsed.hot) {
+    if (parsed.hot && !quiet) {
         console.error("Hot: discarding the first throughput run; models stay loaded (no unload between models).");
     }
     if (parsed.settings.think === true) {
@@ -688,7 +690,7 @@ export async function main() {
         const info = tags.find((t) => t.name === model);
         const caps = await fetchCapabilities(baseUrl, model);
         const selfJudge = Boolean(judgeModel && judgeModel === model);
-        if (!parsed.json) {
+        if (!parsed.json && showProgress()) {
             console.error(`\n→ ${model} (${mi + 1}/${selected.length})`);
         }
         const cold = parsed.coldLoad
@@ -833,7 +835,7 @@ export async function main() {
     };
     if (parsed.save) {
         const file = await saveBenchmark(result);
-        if (!parsed.json)
+        if (!parsed.json && !quiet)
             console.error(`saved ${file}`);
     }
     if (parsed.json) {
@@ -842,7 +844,7 @@ export async function main() {
     else {
         process.stdout.write("\n");
         printTable(machineLabel, parsed.suite, parsed.runs, revision, compKey, modelResults, skipped, parsed.coldLoad, parsed.hot);
-        if (parsed.save)
+        if (parsed.save && !quiet)
             console.error(`benchmarks dir: ${benchmarksDir()}`);
     }
     if (parsed.failOnError && anyError) {

package/dist/cli.d.ts

@@ -12,5 +12,6 @@
  *   ollanet bench <machine> [model...]
  *   ollanet chats
  *   ollanet mcp
+ *   ollanet serve [--funnel]
  */
 export {};

package/dist/cli.js

@@ -12,11 +12,10 @@
  *   ollanet bench <machine> [model...]
  *   ollanet chats
  *   ollanet mcp
+ *   ollanet serve [--funnel]
  */
 const HELP = `ollanet: find, manage, and use Ollama on hosts you choose
-
-Discover hosts, manage models, prompt and compare, bench tok/s, and continue
-chats by hash. CLI for humans, MCP for agents, Node for apps.
+CLI for people, MCP for agents (ollanet mcp), Node library for apps (import from "ollanet").
 A reachable host is not a trusted host. pull and rm change the remote host.
 
 Usage:
@@ -24,7 +23,8 @@ Usage:
   ollanet prompt <machine|ip> [model] <prompt...>
   ollanet prompt --chat <hash> <prompt...>
   ollanet prompt <machine|ip> --file <path.txt|.md>
-  ollanet compare <machine> <model> <model> [model...] [--prompt <text> | --file <path>]
+  <command> | ollanet prompt <machine|ip> [model] --stdin
+  ollanet compare <machine> <model> <model> [model...] [--prompt <text> | --file <path> | --stdin]
   ollanet pull <machine|ip> <model>
   ollanet show <machine|ip> <model>
   ollanet rm <machine|ip> <model> --yes
@@ -33,36 +33,64 @@ Usage:
   ollanet bench <machine|ip> [model...] [--all] [options]
   ollanet alias list|add|rm …
   ollanet mcp
+  ollanet serve [--listen <host:port>] [--funnel]  (read-only catalog)
+  ollanet serve status
+  ollanet serve token add|list|rm|prune …
+  ollanet serve label set|rm|list …
   ollanet help [command]
 
 Examples:
-  ollanet scan
-  ollanet scan --lan
-  ollanet scan --last            # print the last saved scan (no network)
-  ollanet prompt localhost "What is MagicDNS?"
-  ollanet prompt localhost --file ./notes.md
-  ollanet compare studio gemma3:12b llama3.2:3b
-  ollanet compare studio gemma3:12b llama3.2:3b --prompt "Explain MagicDNS"
-  ollanet prompt --chat a1b2c3d4e5f6 "Tell me more"
-  ollanet pull studio gemma3:12b
-  ollanet show studio gemma4-ctx32k
-  ollanet rm studio llama3.2:1b --yes
-  ollanet ps studio
-  ollanet chats
-  ollanet alias add desk studio gemma3:12b
-  ollanet prompt desk "hello"  # expands machine + model
-  ollanet bench localhost --all
-  ollanet bench localhost llama3.2:1b --runs 3
-  ollanet bench localhost gemma3:12b --hot --runs 5
-  ollanet help bench           # flags for one command (also: ollanet bench help)
-  ollanet mcp                  # stdio MCP server for agents
+  Find hosts
+    ollanet scan
+    ollanet scan --lan                # also sweep your subnet on port 11434 (opt-in)
+    ollanet scan --last               # print the last saved scan (no network)
+
+  Prompt and chat
+    ollanet prompt localhost "What is MagicDNS?"
+    ollanet prompt localhost --file ./notes.md
+    ollanet alias add desk studio gemma3:12b
+    ollanet prompt desk "hello"       # expands machine + model
+    git diff | ollanet prompt desk "Review this" --stdin -q
+    ollanet prompt --chat a1b2c3d4e5f6 "Tell me more"
+    ollanet chats
+
+  Compare and bench
+    ollanet compare studio gemma3:12b llama3.2:3b
+    ollanet compare studio gemma3:12b llama3.2:3b --prompt "Explain MagicDNS"
+    ollanet bench localhost --all
+    ollanet bench localhost llama3.2:1b --runs 3
+    ollanet bench localhost gemma3:12b --hot --runs 5
+
+  Manage models (pull and rm change the remote host)
+    ollanet pull studio gemma3:12b
+    ollanet show studio gemma4-ctx32k
+    ollanet rm studio llama3.2:1b --yes
+    ollanet ps studio
+
+  Share a read-only catalog
+    ollanet serve token add cloud-agent --expires 30d
+    ollanet serve --funnel            # catalog on https://<device>.<tailnet>.ts.net/
+    ollanet serve status              # local and Funnel URLs of the running server
+    ollanet serve label set studio gpu-box   # agents see gpu-box, not the host name
+    ollanet serve token prune         # expired, or unused 30+ days (asks first)
 
+  Agents and scripts
+    ollanet mcp                       # stdio MCP server for agents
+    ollanet scan --json -q            # machine-readable hosts and models
+
+Every flag and more examples: ollanet help <command>  (or ollanet <command> --help)
+
+Quiet:  -q / --quiet on any command (or OLLANET_QUIET=1): results on stdout,
+        stderr only for errors and warnings
+Progress: compare/bench progress lines only when stderr is a terminal
+        (OLLANET_PROGRESS=1 forces on, 0 off)
 Config: ~/.ollanet/config.json when installed, ./config.json in a checkout
         (override with OLLANET_CONFIG)
 Hosts:  config.hosts, OLLANET_HOSTS, optional Tailscale + --lan
 Aliases: config.aliases — ollanet alias add|list|rm
 Chats:  ~/.ollanet/responses or ./responses (override with OLLANET_RESPONSES_DIR)
 Scan:   ~/.ollanet/last-scan.json or ./last-scan.json (override with OLLANET_LAST_SCAN)
+Serve:  ~/.ollanet/serve.json, token hashes and labels (override with OLLANET_SERVE_FILE)
 `;
 async function main() {
     // pnpm/npm often forward a bare `--`; ignore it.
@@ -105,8 +133,14 @@ async function main() {
         console.log(`ollanet ${pkg.version ?? "0.0.0"}`);
         return;
     }
-    // Strip the subcommand so command modules see their own argv.
-    process.argv = [process.argv[0] ?? "node", process.argv[1] ?? "ollanet", ...argv.slice(1)];
+    // Strip the subcommand so command modules see their own argv. -q / --quiet
+    // is global: it is removed here and read through isQuiet().
+    const { takeQuietFlag } = await import("./argv.js");
+    process.argv = [
+        process.argv[0] ?? "node",
+        process.argv[1] ?? "ollanet",
+        ...takeQuietFlag(argv.slice(1)),
+    ];
     switch (cmd) {
         case "scan":
         case "ls-servers": {
@@ -170,6 +204,11 @@ async function main() {
             await run();
             return;
         }
+        case "serve": {
+            const { main: run } = await import("./serve.js");
+            await run();
+            return;
+        }
         case "alias":
         case "aliases": {
             const { main: run } = await import("./alias.js");

package/dist/compare.js

@@ -1,4 +1,4 @@
-import { readStdinIfPiped } from "./prompt.js";
+import { readPromptStdin } from "./prompt.js";
 /**
  * Head-to-head: one prompt, 2–5 models on the same host.
  *
@@ -7,7 +7,7 @@ import { readStdinIfPiped } from "./prompt.js";
  */
 import { configFromPartial, loadConfig, lookupAlias, machineSettingsForHost, mergeSettings, settingsFromEnv, } from "./config.js";
 import { envInt, ollamaBaseUrl, shortName } from "./hosts.js";
-import { consumeSettingsFlag, failUsage, isHelpFlag, printHelp, takeFlag, takeValue } from "./argv.js";
+import { consumeSettingsFlag, failUsage, isHelpFlag, isQuiet, printHelp, showProgress, takeFlag, takeValue, } from "./argv.js";
 import { resolveTarget } from "./target.js";
 import { ollamaChat, ollamaTags, ollamaUnload, waitUntilUnloaded, } from "./ollama-chat.js";
 import { assemblePrompt, readPromptFile } from "./prompt-input.js";
@@ -29,6 +29,7 @@ export function helpText() {
   ollanet compare <machine> <model> <model> [model...]
   ollanet compare <machine> <model> <model> [model...] --prompt <text>
   ollanet compare <machine> <model> <model> [model...] --file <path.txt|.md>
+  <command> | ollanet compare <machine> <model> <model> [model...] --stdin
 
 Examples:
   ollanet compare studio gemma3:12b llama3.2:3b
@@ -42,6 +43,8 @@ Omit --prompt/--file to use the built-in mesh-host tasting prompt.
 Options:
   --prompt <text>        Prompt text (default: built-in mesh-host prompt)
   --file <path>          Prompt from a .txt or .md file
+  --stdin, -             Wait for stdin to close and use it as the prompt
+                         (no 100ms cutoff for slow producers)
   --system <text>        System prompt
   --temperature <n>
   --num-predict <n>
@@ -50,7 +53,8 @@ Options:
   --think / --no-think
   --unload               Unload each model before the next (fairer tok/s)
   --no-save              Do not write compares/*
-  --json                 Emit the full record on stdout`;
+  --json                 Emit the full record on stdout
+  -q, --quiet            Table only; no notices or saved paths on stderr`;
 }
 function usage() {
     failUsage(helpText());
@@ -62,6 +66,7 @@ function parseArgs(argv) {
     let json = false;
     let save = true;
     let unload = false;
+    let stdin = false;
     const settings = {};
     const positional = [];
     while (args.length > 0) {
@@ -82,6 +87,10 @@ function parseArgs(argv) {
             unload = true;
             continue;
         }
+        if (arg === "--stdin" || arg === "-") {
+            stdin = true;
+            continue;
+        }
         if (consumeSettingsFlag(arg, args, settings, usage, {
             temperature: true,
             numPredict: true,
@@ -105,7 +114,7 @@ function parseArgs(argv) {
     }
     const machine = positional[0];
     const models = positional.slice(1);
-    return { machine, models, prompt, file, json, save, unload, settings };
+    return { machine, models, prompt, file, json, save, unload, stdin, settings };
 }
 function tokPerSec(chunk) {
     if (chunk.eval_count == null || chunk.eval_duration == null || chunk.eval_duration <= 0) {
@@ -121,19 +130,20 @@ function resolveModelName(available, query) {
     const prefix = available.filter((n) => n.toLowerCase().startsWith(`${q}:`) || q.startsWith(`${n.toLowerCase()}:`));
     return prefix.length === 1 ? prefix[0] : undefined;
 }
+/** Result table on stdout (like bench); notices and saved paths stay on stderr. */
 function printSummary(record) {
     const nameWidth = Math.max(8, ...record.results.map((r) => r.model.length));
-    process.stderr.write(`Compare on ${record.machine}  ${record.results.length} models  ${record.prompt.length} char prompt\n`);
-    process.stderr.write(`${"model".padEnd(nameWidth)}  ${"tok/s".padStart(7)}  ${"tokens".padStart(6)}  ${"wall".padStart(7)}  done\n`);
+    process.stdout.write(`Compare on ${record.machine}  ${record.results.length} models  ${record.prompt.length} char prompt\n`);
+    process.stdout.write(`${"model".padEnd(nameWidth)}  ${"tok/s".padStart(7)}  ${"tokens".padStart(6)}  ${"wall".padStart(7)}  done\n`);
     for (const r of record.results) {
         if (r.error) {
-            process.stderr.write(`${r.model.padEnd(nameWidth)}  ERROR  ${r.error}\n`);
+            process.stdout.write(`${r.model.padEnd(nameWidth)}  ERROR  ${r.error}\n`);
             continue;
         }
         const toks = r.tok_s != null ? r.tok_s.toFixed(1) : "—";
         const tokens = r.eval_count != null ? String(r.eval_count) : "—";
         const wall = r.wall_ms != null ? `${(r.wall_ms / 1000).toFixed(2)}s` : "—";
-        process.stderr.write(`${r.model.padEnd(nameWidth)}  ${toks.padStart(7)}  ${tokens.padStart(6)}  ${wall.padStart(7)}  ${r.done_reason ?? "—"}\n`);
+        process.stdout.write(`${r.model.padEnd(nameWidth)}  ${toks.padStart(7)}  ${tokens.padStart(6)}  ${wall.padStart(7)}  ${r.done_reason ?? "—"}\n`);
     }
 }
 export async function runCompare(opts) {
@@ -173,7 +183,7 @@ export async function runCompare(opts) {
         }
     }
     const settings = mergeSettings({ think: false }, config.defaults, machineSettingsForHost(config, host), settingsFromEnv(), opts.settings);
-    const quiet = opts.quiet === true || opts.writeStdout === false;
+    const quiet = opts.quiet === true || opts.writeStdout === false || !showProgress();
     const results = [];
     for (let i = 0; i < resolved.length; i += 1) {
         const model = resolved[i];
@@ -253,8 +263,17 @@ export async function main() {
         // `compare desk other:7b` → alias model vs other on alias host
         models = [alias.model, models[0]];
     }
-    // Same guarded read as prompt: a never-closing pipe (agents, CI) must not hang.
-    const fromStdin = await readStdinIfPiped();
+    // Same stdin rules as prompt: --stdin waits for EOF; otherwise a guarded read
+    // so a never-closing pipe (agents, CI) cannot hang.
+    let fromStdin;
+    try {
+        fromStdin = await readPromptStdin(parsed.stdin);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+        return;
+    }
     let fileText;
     if (parsed.file) {
         try {
@@ -267,6 +286,10 @@ export async function main() {
         }
     }
     const prompt = assemblePrompt({ argv: parsed.prompt, file: fileText, stdin: fromStdin });
+    const quiet = isQuiet();
+    if (!prompt && !quiet) {
+        process.stderr.write("Using default compare prompt (pass --prompt or --file to override).\n");
+    }
     const record = await runCompare({
         machine,
         models,
@@ -278,15 +301,12 @@ export async function main() {
         quiet: parsed.json,
         config,
     });
-    if (record.default_prompt) {
-        process.stderr.write("Using default compare prompt (pass --prompt or --file to override).\n");
-    }
     if (parsed.json) {
         process.stdout.write(`${JSON.stringify(record, null, 2)}\n`);
         return;
     }
     printSummary(record);
-    if (record.files) {
+    if (record.files && !quiet) {
         process.stderr.write(`saved ${record.files.md}\n`);
         process.stderr.write(`      ${record.files.json}\n`);
         process.stderr.write(`compares dir: ${comparesDir()}\n`);

package/dist/funnel.d.ts

@@ -0,0 +1,70 @@
+export interface ExecResult {
+    /** Exit code, or null when the process could not start or was killed. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    /** The binary was not found. */
+    missing: boolean;
+}
+export interface ExecOptions {
+    timeoutMs: number;
+    /** Stop early (kill the process) once combined output matches. */
+    until?: RegExp;
+}
+export type TailscaleExec = (args: string[], opts: ExecOptions) => Promise<ExecResult>;
+export type TailscaleExecSync = (args: string[], opts: {
+    timeoutMs: number;
+}) => ExecResult;
+export declare const FUNNEL_PORTS: readonly [443, 8443, 10000];
+export declare const HTTPS_ADMIN_URL = "https://login.tailscale.com/admin/dns";
+export declare const FUNNEL_DOCS_URL = "https://tailscale.com/kb/1223/funnel";
+export declare const defaultExec: TailscaleExec;
+export declare const defaultExecSync: TailscaleExecSync;
+/** A Funnel setup problem with a message meant for the person at the terminal. */
+export declare class FunnelError extends Error {
+    readonly enableUrl?: string | undefined;
+    constructor(message: string, enableUrl?: string | undefined);
+}
+interface TailscaleSelf {
+    DNSName?: string;
+    CapMap?: Record<string, unknown>;
+    Capabilities?: string[];
+}
+export interface Preflight {
+    /** MagicDNS name without the trailing dot. */
+    dnsName: string;
+    /** Funnel node attribute present (Self.CapMap / Capabilities). */
+    funnelAllowed: boolean;
+}
+export declare function hasFunnelCap(self: TailscaleSelf | undefined): boolean;
+/** `tailscale status --json`: installed, running, MagicDNS name, HTTPS certs, Funnel attr. */
+export declare function preflight(exec?: TailscaleExec): Promise<Preflight>;
+export declare function funnelOnArgs(funnelPort: number, target: string): string[];
+export declare function funnelOffArgs(funnelPort: number): string[];
+export declare function publicUrl(dnsName: string, funnelPort: number): string;
+/**
+ * What `tailscale funnel status --json` serves at https://<dns>:<port>/.
+ * Returns the proxy target, null when nothing is configured there, or
+ * undefined when the status could not be read.
+ */
+export declare function currentHandler(exec: TailscaleExec, dnsName: string, funnelPort: number): Promise<string | null | undefined>;
+export interface FunnelHandle {
+    publicUrl: string;
+    /** False when an identical funnel was already up; stop() then leaves it alone. */
+    added: boolean;
+    /** Turn off only what we added. Synchronous so it can run in an exit handler. */
+    stop(): void;
+}
+export interface StartFunnelOptions {
+    localPort: number;
+    /** Local URL Funnel proxies to, e.g. http://127.0.0.1:11500 */
+    target: string;
+    funnelPort: number;
+    exec?: TailscaleExec;
+    execSync?: TailscaleExecSync;
+    /** Time allowed for `tailscale funnel --bg` (default 30s). */
+    timeoutMs?: number;
+}
+export declare function startFunnel(opts: StartFunnelOptions): Promise<FunnelHandle>;
+export {};