tailctl 0.1.0__py3-none-any.whl

tailctl/tailscale.py

@@ -0,0 +1,365 @@
+"""Thin, side-effect-free wrapper around the Tailscale CLI.
+
+All subprocess invocations use ``shell=False`` with an argv list so config
+values flow through ``execve`` arguments, never shell strings. Profile names,
+account IDs, and exit-node values are validated upstream (config-load time)
+against ``^[A-Za-z0-9._-]+$``, so they can pass through without quoting.
+
+This module knows nothing about the registry, holders, or instance lifecycle.
+It just runs commands (optionally against a per-instance ``--socket``) and parses
+JSON. Higher-level orchestration lives in ``instance_manager.py``.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+DEFAULT_BINARY = "/Applications/Tailscale.app/Contents/MacOS/Tailscale"
+
+# Convergence + verification timeouts (seconds). Tuned conservative — the
+# Round-2 review flagged 5s as unrealistic for account swaps that re-handshake
+# WireGuard and fetch a fresh netmap.
+DEFAULT_CONVERGENCE_TIMEOUT_S = 20.0
+DEFAULT_CONVERGENCE_POLL_INTERVAL_S = 0.5
+DEFAULT_SUBPROCESS_TIMEOUT_S = 30.0
+
+
+# --- exceptions ---
+
+
+class TailscaleError(RuntimeError):
+    """Generic Tailscale CLI failure (non-zero exit, parse error, timeout)."""
+
+
+class TailscaleConvergenceTimeout(TailscaleError):
+    """Tailscale daemon did not converge to the expected state in time."""
+
+
+# --- types ---
+
+
+@dataclass(frozen=True)
+class SwitchAccount:
+    """One row from ``tailscale switch --list --json``."""
+
+    id: str
+    nickname: str
+    tailnet: str
+    account: str
+    selected: bool
+
+
+@dataclass(frozen=True)
+class ExitNodeStatus:
+    """Minimal projection of ``ExitNodeStatus`` in status --json.
+
+    ``id`` is Tailscale's opaque short ID (e.g. ``nKKJQbqKax11CNTRL``).
+    ``hostname`` is the human name from the matching ``Peer`` entry — what
+    users put in ``profiles.yaml`` under ``exit_node:``. It's resolved by
+    ``parse_status`` joining ``ExitNodeStatus.ID`` against ``Peer[*].ID``;
+    ``None`` when the peer entry isn't present (e.g. during reconnect).
+    """
+
+    id: str | None
+    online: bool
+    hostname: str | None = None
+
+
+@dataclass(frozen=True)
+class TailscaleStatus:
+    """Minimal projection of ``tailscale status --json`` for our needs."""
+
+    backend_state: str
+    current_tailnet_name: str | None
+    exit_node: ExitNodeStatus | None
+    # The raw dict is preserved so the caller can pull arbitrary fields
+    # (e.g. for forensic logging) without re-parsing.
+    raw: dict[str, Any]
+
+
+# --- subprocess seam ---
+
+
+class CommandRunner(Protocol):
+    """Seam for unit tests: replace subprocess with a fake.
+
+    Returns ``(returncode, stdout, stderr)``. Implementations MUST NOT raise
+    on non-zero exit — the wrapper decides what's an error.
+    """
+
+    def __call__(
+        self, argv: list[str], *, timeout: float | None = None
+    ) -> tuple[int, str, str]: ...
+
+
+def real_runner(argv: list[str], *, timeout: float | None = None) -> tuple[int, str, str]:
+    """Production runner: ``subprocess.run`` with shell=False, check=False."""
+    proc = subprocess.run(
+        argv,
+        shell=False,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+    return proc.returncode, proc.stdout, proc.stderr
+
+
+# --- client ---
+
+
+class TailscaleClient:
+    """High-level interface to the Tailscale CLI."""
+
+    def __init__(
+        self,
+        *,
+        binary: str = DEFAULT_BINARY,
+        runner: CommandRunner | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        clock: Callable[[], float] = time.monotonic,
+        socket: str | None = None,
+    ) -> None:
+        self._binary = binary
+        self._runner = runner or real_runner
+        self._sleep = sleep
+        self._clock = clock
+        # When set, every CLI invocation targets a specific (userspace)
+        # tailscaled via its UDS, instead of the machine-global daemon. On
+        # macOS the CLI otherwise defaults to [::1]:64511, so this MUST be
+        # passed explicitly to drive a per-identity instance.
+        self._socket = socket
+
+    def _argv(self, *rest: str) -> list[str]:
+        """Build a CLI argv, prepending --socket when this client is bound to
+        a specific daemon socket."""
+        head = [self._binary]
+        if self._socket:
+            head.append(f"--socket={self._socket}")
+        return [*head, *rest]
+
+    # --- raw probes ---
+
+    def switch_list(self) -> list[SwitchAccount]:
+        """Return all signed-in accounts. Equivalent of ``switch --list --json``."""
+        rc, stdout, stderr = self._runner(
+            self._argv("switch", "--list", "--json"),
+            timeout=DEFAULT_SUBPROCESS_TIMEOUT_S,
+        )
+        if rc != 0:
+            raise TailscaleError(f"switch --list --json failed (rc={rc}): {stderr.strip()}")
+        return parse_switch_list(stdout)
+
+    def status(self) -> TailscaleStatus:
+        """Return ``tailscale status --json`` parsed into a minimal projection."""
+        rc, stdout, stderr = self._runner(
+            self._argv("status", "--json"),
+            timeout=DEFAULT_SUBPROCESS_TIMEOUT_S,
+        )
+        if rc != 0:
+            raise TailscaleError(f"status --json failed (rc={rc}): {stderr.strip()}")
+        return parse_status(stdout)
+
+    def active_account(self) -> SwitchAccount | None:
+        for acct in self.switch_list():
+            if acct.selected:
+                return acct
+        return None
+
+    # --- mutators ---
+
+    def switch_account(self, account_id: str) -> None:
+        """Issue ``tailscale switch <id>``. Does NOT wait for convergence."""
+        rc, _stdout, stderr = self._runner(
+            self._argv("switch", account_id),
+            timeout=DEFAULT_SUBPROCESS_TIMEOUT_S,
+        )
+        if rc != 0:
+            raise TailscaleError(
+                f"switch {account_id} failed (rc={rc}): {stderr.strip()}"
+            )
+
+    def set_exit_node(self, exit_node: str | None) -> None:
+        """Issue ``tailscale set --exit-node=<name>`` (empty = clear)."""
+        value = exit_node or ""
+        rc, _stdout, stderr = self._runner(
+            self._argv("set", f"--exit-node={value}"),
+            timeout=DEFAULT_SUBPROCESS_TIMEOUT_S,
+        )
+        if rc != 0:
+            raise TailscaleError(
+                f"set --exit-node={value!r} failed (rc={rc}): {stderr.strip()}"
+            )
+
+    def up(
+        self,
+        *,
+        accept_routes: bool = True,
+        accept_dns: bool = False,
+        exit_node: str | None = None,
+        hostname: str | None = None,
+        auth_key: str | None = None,
+        timeout_s: float = DEFAULT_SUBPROCESS_TIMEOUT_S,
+    ) -> tuple[int, str, str]:
+        """Issue ``tailscale up`` against this client's (userspace) daemon.
+
+        With ``auth_key`` the login is non-interactive and returns once the
+        node is registered. Without it, a first-time login blocks/prints an
+        auth URL on stdout for the caller to surface; an already-authed
+        statedir returns rc=0 immediately. Subprocess timeout still raises.
+
+        The auth key is passed via argv to the tailscale CLI; it is never
+        included in this wrapper's logs or error messages.
+        """
+        argv = self._argv("up")
+        argv.append(f"--accept-routes={'true' if accept_routes else 'false'}")
+        argv.append(f"--accept-dns={'true' if accept_dns else 'false'}")
+        if exit_node:
+            argv.append(f"--exit-node={exit_node}")
+        if hostname:
+            argv.append(f"--hostname={hostname}")
+        if auth_key:
+            argv.append(f"--auth-key={auth_key}")
+        return self._runner(argv, timeout=timeout_s)
+
+    def logout(self) -> None:
+        """Deregister this daemon's node (clears the statedir's login)."""
+        self._runner(self._argv("logout"), timeout=DEFAULT_SUBPROCESS_TIMEOUT_S)
+
+    # --- convergence ---
+
+    def wait_for_backend_running_and_tailnet(
+        self,
+        *,
+        expected_tailnet: str | None,
+        timeout_s: float = DEFAULT_CONVERGENCE_TIMEOUT_S,
+        poll_interval_s: float = DEFAULT_CONVERGENCE_POLL_INTERVAL_S,
+    ) -> TailscaleStatus:
+        """Poll status until ``BackendState == Running`` and (optionally) the
+        active tailnet matches ``expected_tailnet``.
+
+        ``expected_tailnet`` may be ``None`` or empty to skip the tailnet
+        check (used when the active account has no tailnet name, e.g. a
+        personal account).
+        """
+        deadline = self._clock() + timeout_s
+        last: TailscaleStatus | None = None
+        while True:
+            try:
+                last = self.status()
+            except TailscaleError:
+                last = None
+            if last is not None and last.backend_state == "Running":
+                if not expected_tailnet or last.current_tailnet_name == expected_tailnet:
+                    return last
+            if self._clock() >= deadline:
+                raise TailscaleConvergenceTimeout(
+                    f"backend did not reach Running/{expected_tailnet!r} within "
+                    f"{timeout_s}s (last={last!r})"
+                )
+            self._sleep(poll_interval_s)
+
+
+# --- parsers ---
+
+
+def parse_switch_list(stdout: str) -> list[SwitchAccount]:
+    """Parse ``switch --list --json`` output into typed records."""
+    try:
+        data = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        raise TailscaleError(f"switch --list --json: invalid JSON: {exc}") from exc
+    if not isinstance(data, list):
+        raise TailscaleError("switch --list --json: expected a JSON array")
+    out: list[SwitchAccount] = []
+    for i, entry in enumerate(data):
+        if not isinstance(entry, dict):
+            raise TailscaleError(f"switch --list --json: entry {i} is not an object")
+        try:
+            out.append(
+                SwitchAccount(
+                    id=str(entry["id"]),
+                    nickname=str(entry.get("nickname", "")),
+                    tailnet=str(entry.get("tailnet", "")),
+                    account=str(entry.get("account", "")),
+                    selected=bool(entry["selected"]),
+                )
+            )
+        except KeyError as exc:
+            raise TailscaleError(
+                f"switch --list --json: entry {i} missing key {exc.args[0]!r}"
+            ) from exc
+    return out
+
+
+def parse_status(stdout: str) -> TailscaleStatus:
+    """Parse ``status --json`` into the minimal projection used internally."""
+    try:
+        data = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        raise TailscaleError(f"status --json: invalid JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise TailscaleError("status --json: expected a JSON object")
+    backend_state = data.get("BackendState")
+    if not isinstance(backend_state, str):
+        raise TailscaleError("status --json: missing or non-string BackendState")
+    tailnet_name: str | None = None
+    current_tailnet = data.get("CurrentTailnet")
+    if isinstance(current_tailnet, dict):
+        name = current_tailnet.get("Name")
+        if isinstance(name, str) and name:
+            tailnet_name = name
+    exit_node: ExitNodeStatus | None = None
+    ens = data.get("ExitNodeStatus")
+    if isinstance(ens, dict):
+        en_id = str(ens["ID"]) if isinstance(ens.get("ID"), str) else None
+        exit_node = ExitNodeStatus(
+            id=en_id,
+            online=bool(ens.get("Online", False)),
+            hostname=_resolve_exit_node_hostname(data, en_id),
+        )
+    return TailscaleStatus(
+        backend_state=backend_state,
+        current_tailnet_name=tailnet_name,
+        exit_node=exit_node,
+        raw=data,
+    )
+
+
+def _resolve_exit_node_hostname(
+    status_data: dict[str, Any], exit_node_id: str | None
+) -> str | None:
+    """Join ExitNodeStatus.ID against Peer[*].ID (and Self) to find the
+    human hostname.
+
+    Tailscale reports the active exit node by opaque internal ID; users
+    write profiles.yaml using the peer's HostName. Without this join, a
+    correctly-configured exit node looks like drift.
+
+    Self is checked alongside Peer because a node advertising itself as an
+    exit node appears in Self, not Peer — uncommon but legal.
+
+    Returns None when the ID is absent or no node matches (treat as
+    unverified — callers should not flag drift in that case).
+    """
+    if not exit_node_id:
+        return None
+    candidates: list[dict[str, Any]] = []
+    self_node = status_data.get("Self")
+    if isinstance(self_node, dict):
+        candidates.append(self_node)
+    peers = status_data.get("Peer")
+    if isinstance(peers, dict):
+        candidates.extend(p for p in peers.values() if isinstance(p, dict))
+    for node in candidates:
+        if node.get("ID") == exit_node_id:
+            host = node.get("HostName")
+            if isinstance(host, str) and host:
+                return host
+            return None
+    return None

tailctl-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: tailctl
+Version: 0.1.0
+Summary: Per-identity Tailscale networking for parallel sessions on a single Mac
+Author-email: DRYCodeWorks <dan@drycodeworks.com>
+License: MIT
+Project-URL: Homepage, https://drycodeworks.com
+Project-URL: Repository, https://github.com/DRYCodeWorks/tailctl
+Project-URL: Issues, https://github.com/DRYCodeWorks/tailctl/issues
+Keywords: tailscale,vpn,wireguard,networking,socks5,proxy,cli,macos,multi-account,ai-agents,parallel-sessions
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: psutil>=5.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-timeout>=2.2; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/DRYCodeWorks/tailctl/main/docs/tailctl-banner.jpg" alt="tailctl — per-identity Tailscale networking for parallel sessions on a single Mac" width="100%">
+</p>
+
+# tailctl
+
+Per-identity Tailscale networking for parallel sessions on a single Mac.
+
+`tailctl` gives each process (e.g. a Claude Code session in its own Ghostty window)
+its **own** Tailscale identity — a private, headless userspace `tailscaled` with a
+per-identity SOCKS5/HTTP proxy and localhost port-forwards — instead of switching
+the machine-global Tailscale account. Many identities run at once, and the GUI
+Tailscale app (the browser's default tailnet) is never touched. No FIFO queue, no
+shared network, no flapping.
+
+Agent traffic is opted in per command via proxy env vars (`tailctl run`) or stable
+localhost forwards for native-TCP clients (ClickHouse, Postgres, …).
+
+No always-on daemon beyond the per-identity tailscaled instances. Single-laptop scope.
+
+## Status
+
+Working prototype — macOS-only, single-laptop scope.
+
+## Install
+
+Requires macOS, Python 3.11+, and the Homebrew Tailscale daemon (see
+[Requirements](#requirements)).
+
+```
+brew install tailscale
+pipx install tailctl        # or: pip install tailctl
+```
+
+Or from source:
+
+```
+brew install tailscale
+git clone https://github.com/DRYCodeWorks/tailctl && cd tailctl
+python3 -m venv .venv && .venv/bin/pip install -e .
+ln -sf "$PWD/.venv/bin/tailctl" ~/.local/bin/tailctl   # put it on PATH
+```
+
+## Quick view
+
+```
+tailctl init                       # scaffold ~/.tailctl/profiles.yaml
+tailctl doctor                     # validate config + probe daemon + verify accounts
+tailctl bootstrap <name> --tailnet <t> [--exit-node <e>] [--port-forward svc=host:port]
+                                   # onboard a NEW tailnet: discovers account_id,
+                                   #   appends a profile (preserving comments), prints
+                                   #   the key steps (mint in console -> store in BWS)
+tailctl up acme-dev              # spawn a userspace tailscaled for the profile
+                                   #   (first time: prints a one-time auth URL)
+tailctl run acme-dev -- curl http://service.internal   # route a command via that identity
+tailctl run acme-dev -- clickhouse-client --host 127.0.0.1 --port $CLICKHOUSE_ADDR
+tailctl ps                         # list running instances + their proxy ports/forwards
+tailctl down acme-dev            # release (refcount--); stops the daemon at zero
+```
+
+`run` sets `ALL_PROXY`/`HTTPS_PROXY`/`HTTP_PROXY` (+ `NO_PROXY`) so proxy-aware
+clients route through the identity, and exports `<SERVICE>_ADDR=127.0.0.1:<port>`
+for each configured `port_forward` so native-TCP clients connect to localhost.
+
+## profiles.yaml
+
+```yaml
+default: acme-dev
+tailscaled_binary: /opt/homebrew/opt/tailscale/bin/tailscaled
+profiles:
+  acme-dev:
+    account_id: a2c4
+    tailnet: acme.example.ts.net
+    exit_node: tailscale-subnet-router-development
+    accept_routes: true
+    auth_key_env: ACME_TS_AUTHKEY   # optional: env var holding a Tailscale
+                                      # auth key (from BWS) for non-interactive
+                                      # first login — no browser URL
+    port_forwards:
+      - service: clickhouse        # exported as CLICKHOUSE_ADDR
+        remote_host: 100.64.0.10
+        remote_port: 9000
+```
+
+## Authentication
+
+Each profile is a distinct device on its tailnet, authenticated **once** — the
+login persists in the profile's statedir and is reused on every later `up`/`run`
+(teardown never logs out). Two ways to do that one-time login:
+
+- **Auth key (recommended):** set `auth_key_env` to an env var holding a
+  Tailscale auth key (minted in the tailnet's admin console, stored in BWS).
+  First `up` logs in non-interactively — no browser.
+- **Interactive:** with no auth key, the first `up` prints a login URL to open
+  once.
+
+Profiles that share an account but differ by exit node (e.g. Acme
+dev/staging/prod) are separate profiles → separate nodes → one auth each.
+
+## Requirements
+
+- macOS
+- Homebrew Tailscale for the userspace daemon: `brew install tailscale`
+  (coexists with the GUI Tailscale.app, which keeps the browser's default tailnet)
+- Python 3.11+
+- Each profile's Tailscale account authenticated once per profile on first `up`
+
+## License
+
+MIT

tailctl-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+tailctl/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+tailctl/cli.py,sha256=WCJEWvINo9bn6T_Je6PhIYzD7LuaA5ZWrOS22WgVeiQ,24055
+tailctl/config.py,sha256=mdLf3f-FljubE2n31RL-LrzMgIhnpoOWsCzszHcYmwk,11233
+tailctl/forwarder.py,sha256=puLpCMWRID8qUB1P3eLl94PQjuwcow8DWd3rU3IzEDI,4606
+tailctl/instance_manager.py,sha256=qCpIc_Uc0LSl27WYiKbl_tZzwp3aP8IVidG2EsT90-w,37379
+tailctl/liveness.py,sha256=-qeFpMlkL0a-nKoB7O22YVDjA-F5REAKZ8qnWUC65FU,4967
+tailctl/log.py,sha256=6H0rRPqe5iMjoD9gBhMD1JgtSrmrnWW9TcITpErJPh4,1368
+tailctl/paths.py,sha256=S0_XwxphmiRf6gWqLDTikqi59u7_UwakQt9y7wajn08,2026
+tailctl/profiles.py,sha256=TSTwr-GSRpkZrnuG_-DHN6f-FRqixUixopiVvxBupOY,2270
+tailctl/registry.py,sha256=380McJU1EAfVIyWukCPv2DfbHTY-mEFFvhI5wLe5N-Y,6300
+tailctl/signals.py,sha256=ZvLbmPY6dMAzHko8GPS3kFRYeSh66WjspDB1wuu1hfM,1753
+tailctl/tailscale.py,sha256=hCrojMxhRrmiyoJpVmATfLFZQt3kq4vnswP3LjpxvKw,13005
+tailctl-0.1.0.dist-info/licenses/LICENSE,sha256=tCJ1mJyU60MYqdPDvF-E5lFzcloGJkHszr4qRp-MC8A,1069
+tailctl-0.1.0.dist-info/METADATA,sha256=oTbMFjAlxHqbXNciWQ5K8X1JfFTyp2UuNbiFdSgwWzg,5736
+tailctl-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+tailctl-0.1.0.dist-info/entry_points.txt,sha256=ZCJHEcit4mUTBAJ1kqQL8O3hfmO6olHo8rTBtt-e0ss,45
+tailctl-0.1.0.dist-info/top_level.txt,sha256=_9CWOOPeY9wB1f_ch9A7jdpHpAEzQM_OiCEBpmztjzk,8
+tailctl-0.1.0.dist-info/RECORD,,

tailctl-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tailctl-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tailctl = tailctl.cli:main

tailctl-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DRYCodeWorks
+
+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.

tailctl-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tailctl