tailctl 0.1.0__tar.gz

tailctl-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,110 @@
+<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/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tailctl"
+version = "0.1.0"
+description = "Per-identity Tailscale networking for parallel sessions on a single Mac"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "DRYCodeWorks", email = "dan@drycodeworks.com" }]
+keywords = [
+    "tailscale",
+    "vpn",
+    "wireguard",
+    "networking",
+    "socks5",
+    "proxy",
+    "cli",
+    "macos",
+    "multi-account",
+    "ai-agents",
+    "parallel-sessions",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Networking",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "PyYAML>=6.0",
+    "psutil>=5.9",
+]
+
+[project.urls]
+Homepage = "https://drycodeworks.com"
+Repository = "https://github.com/DRYCodeWorks/tailctl"
+Issues = "https://github.com/DRYCodeWorks/tailctl/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-timeout>=2.2",
+    "ruff>=0.4",
+]
+
+[project.scripts]
+tailctl = "tailctl.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q --strict-markers"
+markers = [
+    "integration: requires real tailscale CLI; not run by default",
+    "smoke: parallel smoke test; requires TAILCTL_RUN_REAL_TAILSCALE=1",
+]
+timeout = 10
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]

tailctl-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tailctl-0.1.0/src/tailctl/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"