devops-bot-sdk 1.6.34__tar.gz → 1.6.37__tar.gz

{devops_bot_sdk-1.6.34 → devops_bot_sdk-1.6.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.34
+Version: 1.6.37
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.34 → devops_bot_sdk-1.6.37}/devops_bot_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.34
+Version: 1.6.37
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.34 → devops_bot_sdk-1.6.37}/devops_bot_sdk.egg-info/SOURCES.txt

@@ -16,6 +16,7 @@ sdk/crucial.py
 sdk/departments.py
 sdk/estimator.py
 sdk/exceptions.py
+sdk/firewall.py
 sdk/formats.py
 sdk/git_ops.py
 sdk/github_ingest.py
@@ -38,6 +39,7 @@ sdk/scheduler.py
 sdk/self_report.py
 sdk/self_report_local.py
 sdk/sse.py
+sdk/swagger.py
 sdk/task_file.py
 sdk/task_types.py
 sdk/test.py
@@ -112,7 +114,6 @@ sdk/ui/static/chat.html
 sdk/ui/static/custom-agents.html
 sdk/ui/static/default-agents.html
 sdk/ui/static/index.html
-sdk/ui/static/login.html
 sdk/ui/static/report.html
 sdk/ui/static/runs.html
 sdk/ui/static/schedules.html
@@ -152,7 +153,6 @@ tests/test_health.py
 tests/test_intake_plan_review.py
 tests/test_journal.py
 tests/test_local_exec_provider.py
-tests/test_otp_login.py
 tests/test_phase_timer.py
 tests/test_plan_new_command.py
 tests/test_plan_run_activity.py
@@ -168,12 +168,15 @@ tests/test_schedule_api.py
 tests/test_scheduler.py
 tests/test_self_report.py
 tests/test_service_token_warning.py
+tests/test_swagger_command.py
 tests/test_task_file_and_plan_run.py
 tests/test_task_file_format_doc.py
 tests/test_ticket_fields.py
 tests/test_ticket_run_resolve_by_id.py
 tests/test_ticket_speed_fixes.py
 tests/test_tier_flag_parity.py
+tests/test_ui_gate.py
+tests/test_ui_lifespan.py
 tests/test_update_timer.py
 tests/test_updater_extras.py
 tests/test_url_access.py

{devops_bot_sdk-1.6.34 → devops_bot_sdk-1.6.37}/devops_bot_sdk.egg-info/entry_points.txt

@@ -2,4 +2,5 @@
 agentos = sdk.cli:main
 agentos-agentd = sdk.agentd:main
 agentos-auto = sdk.run_auto:main
+agentos-swagger = sdk.swagger:main
 agentos-ui = sdk.ui.server:main

{devops_bot_sdk-1.6.34 → devops_bot_sdk-1.6.37}/pyproject.toml

@@ -54,6 +54,7 @@ agentos = "sdk.cli:main"                    # unified CLI: configure/agent/integ
 agentos-auto = "sdk.run_auto:main"          # run orchestrate-auto LOCALLY (co_ token from config)
 agentos-agentd = "sdk.agentd:main"          # long-running custom-agent daemon
 agentos-ui = "sdk.ui.server:main"           # local web control panel (needs the [ui] extra)
+agentos-swagger = "sdk.swagger:main"        # where /docs is + can you reach it (= `agentos swagger`)
 
 [project.urls]
 Homepage   = "https://agentos.io"

{devops_bot_sdk-1.6.34 → devops_bot_sdk-1.6.37}/sdk/__init__.py

@@ -1,6 +1,6 @@
 """AgentOS Desktop SDK — thin HTTPS/SSE client for the Electron app.
 
-Version: 1.6.34
+Version: 1.6.37
 
 Public surface:
   BackendClient.from_config()        — create client from ~/.agentos/config.toml
@@ -34,7 +34,7 @@ Rules:
   - All data egress through submit_webhook only
 """
 
-__version__ = "1.6.34"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
+__version__ = "1.6.37"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
 __author__  = "AgentOS"   # sdk.client.SDK_VERSION and the UI server version all read this.
 
 from sdk.client import BackendClient

{devops_bot_sdk-1.6.34 → devops_bot_sdk-1.6.37}/sdk/cli.py

@@ -58,6 +58,26 @@ Command surface:
     agentos integration rm <name>
         Remove a registered integration.
 
+    agentos firewall [--apply] [--revoke IP] [--port N]
+        Print the host-firewall rules that open the agentos-ui port to every IP in
+        the application allowlist (`sdk.config.get_allowed_ips`), for THIS OS — ufw
+        on Linux, `netsh advfirewall` on Windows, a pf note on macOS. Prints by
+        default; `--apply` executes them and needs root / Administrator. The host
+        firewall is a separate layer the allowlist cannot reach, and the two drifting
+        apart is what silently blinded every VPS when the backend's egress IP moved.
+        See sdk.firewall.
+
+    agentos swagger [--open] [--json [PATH]] [--port N]
+        Where the panel's Swagger UI is and whether it can actually be reached:
+        the URL derived from the bind address the service was installed with,
+        whether a co_ token is configured (masked), how many operations the spec
+        has, and a ufw/netsh diff against sdk.config.get_allowed_ips when the HOST
+        firewall would drop the port — a layer the SDK's own allowlist cannot see.
+        `--open` launches a browser; `--json` writes openapi.json from
+        create_app().openapi() with no server running (`--json -` pipes it).
+        Also flags routes registered twice, since the second copy is dead code.
+        Needs the [ui] extra for the route count and --json. See sdk.swagger.
+
     agentos report submit [--date YYYY-MM-DD] (--text "…" | --file PATH)
                           [--project NAME] [--proof PATH|URL]… [--no-wait]
         Report work that never reached Jira or GitHub, attach proofs (local
@@ -139,6 +159,14 @@ def main() -> None:
         _github_command(rest)
         return
 
+    if noun == "firewall":
+        from sdk import firewall
+        sys.exit(firewall.cli(rest))
+
+    if noun == "swagger":
+        from sdk import swagger
+        sys.exit(swagger.cli(rest))
+
     if noun == "report":
         _report_command(rest)
         return
@@ -152,7 +180,7 @@ def main() -> None:
 
 
 def _print_usage() -> None:
-    print("usage: agentos <configure|chat|agent|integration|default-agents|agentd|github|report|browser> ...")
+    print("usage: agentos <configure|chat|agent|integration|default-agents|agentd|github|report|browser|firewall|swagger> ...")
     print()
     print("  agentos configure [--rotate]")
     print("  agentos chat [--product-id ID] [--pv-id ID] [--no-autorun]   # requirements → ticket")
@@ -164,6 +192,8 @@ def _print_usage() -> None:
     print("  agentos github <ingest [--days N]|status>            # PR ingestion; --days N backfills N days")
     print("  agentos report <submit|list|show ID>                 # report work Jira/GitHub never saw")
     print("  agentos browser <login URL|status|logout>            # sign in once; private links become readable")
+    print("  agentos firewall [--apply] [--revoke IP] [--port N]  # open the UI port to the allowlisted IPs")
+    print("  agentos swagger [--open] [--json [PATH]]             # where /docs is, and can you reach it")
 
 
 # ── agent ────────────────────────────────────────────────────────────────

{devops_bot_sdk-1.6.34 → devops_bot_sdk-1.6.37}/sdk/client.py

@@ -45,6 +45,13 @@ logger = logging.getLogger(__name__)
 # agents without a lookup on every run.
 _AGENT_ID_CACHE: dict[str, str] = {}
 
+# GitHub access token, keyed by the co_ token that fetched it → (token, expires_at
+# monotonic). Keyed per credential so two clients on one box never share a token.
+# Without this the token is re-fetched on EVERY call, which is what
+# tests/test_ticket_speed_fixes.py::TestGithubTokenCache guards against.
+_GITHUB_TOKEN_CACHE: dict[str, tuple[str, float]] = {}
+_GITHUB_TOKEN_TTL_S = float(os.getenv("AGENTOS_GITHUB_TOKEN_TTL_S", "") or 1800.0)
+
 # GitHub access token, keyed by the co_ token that fetched it → (token, expires_at
 # monotonic). Keyed per credential so two clients on one box never share a token.
 _GITHUB_TOKEN_CACHE: dict[str, tuple[str, float]] = {}
@@ -952,51 +959,71 @@ class BackendClient:
         co_ token. Best-effort: returns None on any failure so a run without a
         connected GitHub account still proceeds (clone/PR steps just won't auth).
         """
+        import time as _time
+
+        now = _time.monotonic()
+        cached = _GITHUB_TOKEN_CACHE.get(self._token)
+        if cached and now < cached[1]:
+            return cached[0]
         record = await self.github_token_record()
-        return (record or {}).get("accessToken") or None
+        token = (record or {}).get("accessToken") or None
+        if token:
+            _GITHUB_TOKEN_CACHE[self._token] = (token, now + _GITHUB_TOKEN_TTL_S)
+        return token
 
-    async def ingest_github_prs(self, since: str | None = None) -> dict:
+    async def ingest_github_prs(self, since: str | None = None) -> dict | None:
         """POST {AI}/api/v1/github/prs — trigger this user's daily PR ingestion.
 
-        The backend resolves the caller's GitHub link server-side from the co_
-        token in ``Authorization`` (see ``docs/GITHUB_SCHEDULING_SDK_MIGRATION.md``);
-        ``githubUsername``/``githubAccessToken`` below are placeholders kept only
-        for backends that predate that resolution and are otherwise ignored.
-        ``since`` (ISO-8601 date) scopes the fetch — omit for "today".
-
-        Returns the backend's ``{status, job_id, status_url, ...}`` envelope.
-        Raises BackendUnreachable / HTTP errors — the github_ingest cron catches
-        and logs these itself rather than treating them as success.
+        The daily trigger. The work runs on the AI backend (LLM summarise, the
+        downstream daily-summary forward, the Qdrant upsert); the SDK only decides
+        WHEN, because only this machine knows its own catch-up watermark.
+
+        The backend resolves the caller's GitHub link server-side from the co_ token
+        in ``Authorization`` and OVERWRITES whatever the body sends
+        (``docs/GITHUB_SCHEDULING_SDK_MIGRATION.md`` §7/§9 — that endpoint used to
+        take a GitHub access token in an unauthenticated body). So this deliberately
+        sends NO credentials: a client that still supplied them would be shipping a
+        secret the server ignores.
+
+        ``since`` is an ISO date (``YYYY-MM-DD``) → the backend's ``date_from``.
+        Omitted means "today", which is what a never-missed run wants; the cron sends
+        the watermark instead so a machine that was off does not lose days.
+
+        Returns the response JSON (``{status, job_id, status_url, ...}``) or **None**
+        on any failure — never raises into the cron. WHY it failed lands in
+        ``self.last_ingest_error`` (``{status, body, retryable}``), which the
+        scheduler needs to tell a busy backend (retry in 30 min) from a rejected
+        request (wait for the next slot).
         """
-        body = [{
+        payload = [{
             "userId": self._user_id_from_token(),
-            "githubUsername": "",
-            "githubAccessToken": "",
-            "apiTokenHash": self._token,
-            "date_from": since,
+            "apiTokenHash": self._token,   # downstream daily-summary Authorization
         }]
-        async with httpx.AsyncClient(timeout=30.0) as client:
-            resp = await client.post(
-                self._url("/api/v1/github/prs"), json=body, headers=self._headers,
-            )
-        _check_status(resp.status_code, self._url("/api/v1/github/prs"))
-        return resp.json()
-
-    async def report_vps_health(self, payload: dict) -> dict:
-        """PATCH {AI}/api/v1/vps/health — heartbeat this machine's resource usage.
-
-        Feeds the backend's ``contabo_allocation`` row (VPS health shown in chat /
-        activity reports) — a live GET of the same path answers on-demand checks,
-        this PATCH is what keeps that data from going stale. Raises on failure
-        (BackendUnreachable / HTTP error); the vps_health cron logs and continues
-        rather than crashing the loop.
-        """
-        async with httpx.AsyncClient(timeout=30.0) as client:
-            resp = await client.request(
-                "PATCH", self._url("/api/v1/vps/health"), json=payload, headers=self._headers,
-            )
-        _check_status(resp.status_code, self._url("/api/v1/vps/health"))
-        return resp.json()
+        if since:
+            payload[0]["date_from"] = since
+        self.last_ingest_error = {}
+        try:
+            async with httpx.AsyncClient(timeout=60.0) as client:
+                resp = await client.post(
+                    self._url("/api/v1/github/prs"), json=payload, headers=self._headers,
+                )
+            if resp.status_code >= 400:
+                body = resp.text[:500]
+                logger.warning("client.ingest_github_prs failed status=%s body=%s",
+                               resp.status_code, body[:200])
+                self.last_ingest_error = {
+                    "status": resp.status_code,
+                    "body": body,
+                    "retryable": is_retryable_backend_error(resp.status_code, body),
+                }
+                return None
+            return resp.json()
+        except Exception as exc:  # noqa: BLE001 — a cron must not die on a blip
+            logger.warning("client.ingest_github_prs error err=%s", exc)
+            # A transport failure (timeout, reset, DNS blip) is as retryable as an
+            # exhausted pool — the backend may simply be busy.
+            self.last_ingest_error = {"status": 0, "body": str(exc)[:500], "retryable": True}
+            return None
 
     async def move_to_backlog(self, task_id: str) -> bool:
         """PUT {BE}/tasks-ml/{id} status=backlog (best-effort).

{devops_bot_sdk-1.6.34 → devops_bot_sdk-1.6.37}/sdk/config.py

@@ -192,7 +192,15 @@ def _dotenv_value(key: str) -> str:
 # backend can reach EVERY VPS's /api/ui/* out of the box (no per-VPS .env needed);
 # always allowed, treated as permanent (not removable via the API). Extend/override
 # with AGENTOS_UI_ALLOWED_IPS in .env or the process env.
-_DEFAULT_ALLOWED_IPS: list[str] = ["20.12.201.148"]
+#
+# A LIST, not one value, because the backend's egress address is not stable: when it
+# moved to 20.127.87.169 every VPS silently stopped answering `GET /api/v1/vps/health`
+# (30s hang, then 502 — the SYNs were dropped at the host firewall, observed
+# 2026-09-03). Both addresses stay listed rather than swapping, so a rollback or a
+# blue/green pair does not re-break it. Note the host firewall is a SEPARATE layer this
+# list cannot reach: `sudo ufw allow from <ip> to any port 8765 proto tcp` is still
+# required per VPS. See docs/VPS_HEALTH_AND_GITHUB_INGEST_DIAGNOSIS.md #5.
+_DEFAULT_ALLOWED_IPS: list[str] = ["20.12.201.148", "20.127.87.169"]
 
 
 def _parse_token_list(raw: str) -> list[str]:

devops_bot_sdk-1.6.37/sdk/firewall.py

@@ -0,0 +1,310 @@
+"""Host-firewall rules for the ``agentos-ui`` port — generate, show, apply.
+
+The SDK has **two** independent gates in front of `/api/ui/*`, and only one of
+them is code:
+
+  1. `sdk.config.get_allowed_ips()` + `IPAllowlistMiddleware` — application level,
+     shipped in the wheel, changed by editing `.env` / `config.toml`.
+  2. The **host firewall** — OS level, outside the process entirely.
+
+Nothing in the SDK could reach (2), which is how the backend's egress move to
+`20.127.87.169` silently blinded every VPS: the allowlist said yes, the kernel
+dropped the SYN before the server ever saw it (`docs/VPS_HEALTH_AND_GITHUB_INGEST
+_DIAGNOSIS.md` #5). This module closes that gap by deriving the firewall rules
+from the *same* list the middleware enforces, so the two layers cannot drift.
+
+    agentos firewall              # show the rules for this OS (safe, prints only)
+    agentos firewall --apply      # run them (needs root / Administrator)
+    agentos firewall --revoke IP  # print the matching delete rule
+
+Applying is deliberately opt-in: editing a live firewall is exactly the operation
+that can lock an operator out of their own box, so the default is to print and let
+a human read it first.
+"""
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+import sys
+
+_RULE_TAG = "AgentOS UI"   # stable prefix so rules are findable and removable
+
+
+def ui_port() -> int:
+    """The port `agentos-ui` binds — same resolution the server uses."""
+    try:
+        return int(os.environ.get("AGENTOS_UI_PORT", "8765"))
+    except ValueError:
+        return 8765
+
+
+def _system() -> str:
+    return platform.system().lower()
+
+
+def allow_rules(ips: list[str], port: int, system: str | None = None) -> list[str]:
+    """The commands that open ``port`` to each of ``ips`` — one per IP.
+
+    Linux uses ufw. Windows uses `netsh advfirewall`, whose rule model differs in
+    two ways worth naming: the rule is identified by `name=`, not by its contents,
+    so a stable name is what makes it idempotent-ish and removable; and `remoteip=`
+    accepts a comma-separated list, so all the IPs *could* be one rule — kept as
+    one-rule-per-IP anyway so a single address can be revoked without rewriting
+    the others.
+    """
+    sysname = (system or _system()).lower()
+    out: list[str] = []
+
+    if sysname == "linux":
+        for ip in ips:
+            # `comment` must come last; ufw >= 0.35. Harmless to re-run — ufw
+            # reports "Skipping adding existing rule".
+            out.append(
+                f"sudo ufw allow from {ip} to any port {port} proto tcp "
+                f"comment '{_RULE_TAG}'"
+            )
+    elif sysname == "windows":
+        for ip in ips:
+            out.append(
+                f'netsh advfirewall firewall add rule name="{_RULE_TAG} {port} {ip}" '
+                f"dir=in action=allow protocol=TCP localport={port} remoteip={ip}"
+            )
+    elif sysname == "darwin":
+        # macOS ships pf, which has no per-rule CLI equivalent — rules live in a
+        # file and the anchor is reloaded. Emitted as a here-doc + reload rather
+        # than pretending a one-liner exists.
+        joined = ", ".join(ips) or "none"
+        out.append(
+            f"# macOS (pf) — append to /etc/pf.anchors/agentos then reload:\n"
+            f"#   pass in proto tcp from {{ {joined} }} to any port {port}\n"
+            f"sudo pfctl -f /etc/pf.conf && sudo pfctl -E"
+        )
+    else:
+        out.append(f"# unsupported platform {sysname!r} — open TCP {port} to: "
+                   f"{', '.join(ips) or 'none'}")
+    return out
+
+
+def revoke_rule(ip: str, port: int, system: str | None = None) -> str:
+    """The command that removes the rule for one ``ip``."""
+    sysname = (system or _system()).lower()
+    if sysname == "linux":
+        return f"sudo ufw delete allow from {ip} to any port {port} proto tcp"
+    if sysname == "windows":
+        return (f'netsh advfirewall firewall delete rule '
+                f'name="{_RULE_TAG} {port} {ip}" remoteip={ip}')
+    if sysname == "darwin":
+        return f"# macOS: remove the matching line from /etc/pf.anchors/agentos, then: sudo pfctl -f /etc/pf.conf"
+    return f"# unsupported platform {sysname!r}"
+
+
+def _tool_present() -> tuple[bool, str]:
+    """Is the firewall tool for this OS actually installed?"""
+    sysname = _system()
+    tool = {"linux": "ufw", "windows": "netsh", "darwin": "pfctl"}.get(sysname, "")
+    if not tool:
+        return False, f"no known firewall tool for {sysname}"
+    if shutil.which(tool):
+        return True, tool
+    return False, f"{tool} not found on PATH"
+
+
+def _run(cmd: list[str], timeout: float = 10.0) -> str | None:
+    """Run a read-only query and return stdout, or None if it could not be run."""
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    except Exception:  # noqa: BLE001 — tool missing, no permission, hung
+        return None
+    return proc.stdout if proc.returncode == 0 else None
+
+
+def _parse_ufw(text: str, port: int) -> set[str]:
+    """Sources ufw currently allows to ``port`` (IPv4 rules only).
+
+    Parses the human table, because `ufw status` has no machine format. A row is
+    ``<to>  <action>  <from>`` and the interesting ones look like::
+
+        8765/tcp    ALLOW    20.12.201.148    # app port - requested IP
+        8765/tcp    ALLOW    Anywhere
+
+    ``(v6)`` rows are skipped so the result can be diffed against an IPv4
+    allowlist without spurious "missing" entries.
+    """
+    out: set[str] = set()
+    for line in text.splitlines():
+        line = line.split("#", 1)[0].strip()
+        if not line or "(v6)" in line:
+            continue
+        parts = line.split()
+        if len(parts) < 3 or parts[1].upper() != "ALLOW":
+            continue
+        to = parts[0]
+        if to != str(port) and not to.startswith(f"{port}/"):
+            continue
+        out.add(" ".join(parts[2:]).strip())
+    return out
+
+
+def _parse_netsh(text: str, port: int) -> set[str]:
+    """Sources netsh currently allows to ``port`` (inbound allow rules only).
+
+    `show rule` emits blank-line-separated blocks of ``Key: Value``; a rule matters
+    only when it is inbound, allowing, and its LocalPort covers ``port``.
+    """
+    out: set[str] = set()
+    for block in text.split("\n\n"):
+        fields: dict[str, str] = {}
+        for line in block.splitlines():
+            if ":" in line:
+                k, _, v = line.partition(":")
+                fields[k.strip().lower()] = v.strip()
+        if not fields:
+            continue
+        if fields.get("enabled", "").lower() not in ("yes", ""):
+            continue
+        if fields.get("direction", "").lower() not in ("in", "inbound", ""):
+            continue
+        if fields.get("action", "").lower() not in ("allow", ""):
+            continue
+        ports = {p.strip() for p in fields.get("localport", "").split(",")}
+        if str(port) not in ports and "any" not in {p.lower() for p in ports}:
+            continue
+        for ip in fields.get("remoteip", "").split(","):
+            ip = ip.strip()
+            if ip:
+                out.add("Anywhere" if ip.lower() in ("any", "*") else ip)
+    return out
+
+
+def port_sources(port: int, system: str | None = None) -> set[str] | None:
+    """Which sources the HOST firewall currently allows to ``port``.
+
+    ``{"Anywhere"}`` means open to the world. **``None`` means the state could not
+    be read** — no tool, or not privileged — and a caller must then say "unknown",
+    never "closed": reporting a closed port that is actually open is the more
+    dangerous error of the two.
+
+    Read-only and never raises. This exists because the SDK's own allowlist
+    (`sdk.config.get_allowed_ips`) and the host firewall are separate layers, and
+    the interesting question is where they DISAGREE — an IP the app permits but the
+    kernel drops looks exactly like a broken backend.
+    """
+    sysname = (system or _system()).lower()
+    if sysname == "linux":
+        text = _run(["ufw", "status"])
+        if text is None:
+            return None
+        got = _parse_ufw(text, port)
+        return {"Anywhere"} if "Anywhere" in got else got
+    if sysname == "windows":
+        text = _run(["netsh", "advfirewall", "firewall", "show", "rule",
+                     "name=all", "dir=in"], timeout=25.0)
+        if text is None:
+            return None
+        got = _parse_netsh(text, port)
+        return {"Anywhere"} if "Anywhere" in got else got
+    return None          # macOS pf and anything else: not readable this way
+
+
+def _is_privileged() -> bool:
+    if _system() == "windows":
+        try:
+            import ctypes
+            return bool(ctypes.windll.shell32.IsUserAnAdmin())
+        except Exception:  # noqa: BLE001 — not Windows, or no ctypes
+            return False
+    return hasattr(os, "geteuid") and os.geteuid() == 0
+
+
+def cli(argv: list[str]) -> int:
+    """``agentos firewall [--apply] [--revoke IP] [--port N]``."""
+    from sdk.config import get_allowed_ips
+
+    port = ui_port()
+    if "--port" in argv:
+        try:
+            port = int(argv[argv.index("--port") + 1])
+        except (IndexError, ValueError):
+            print("error: --port needs a number")
+            return 2
+
+    if "--revoke" in argv:
+        try:
+            ip = argv[argv.index("--revoke") + 1]
+        except IndexError:
+            print("error: --revoke needs an IP")
+            return 2
+        print(revoke_rule(ip, port))
+        print("\nAlso remove it from the allowlist, or the next restart re-permits it\n"
+              "at the application layer: AGENTOS_UI_ALLOWED_IPS in ~/.agentos/.env,\n"
+              "or `allowed_ips` in ~/.agentos/config.toml. IPs baked into\n"
+              "sdk.config._DEFAULT_ALLOWED_IPS cannot be removed that way.")
+        return 0
+
+    ips = get_allowed_ips()
+    sysname = _system()
+    print(f"Platform : {platform.system()}  ({sysname})")
+    print(f"UI port  : {port}")
+    print(f"Allowed  : {', '.join(ips) if ips else '(none — loopback only)'}")
+
+    if not ips:
+        print("\nNothing to open. Loopback always reaches the server; add the backend's\n"
+              "egress IP to AGENTOS_UI_ALLOWED_IPS first.")
+        return 0
+
+    rules = allow_rules(ips, port, sysname)
+    print("\nFirewall rules for this host:\n")
+    for r in rules:
+        print(f"  {r}")
+
+    if "--apply" not in argv:
+        ok, tool = _tool_present()
+        print(f"\n(dry run — nothing changed. Firewall tool: {tool})")
+        print("Re-run with --apply to execute, or copy the lines above.")
+        if sysname == "linux":
+            print("Verify after applying:  sudo ufw status")
+        elif sysname == "windows":
+            print(f'Verify after applying:  netsh advfirewall firewall show rule name="{_RULE_TAG} {port} {ips[0]}"')
+        return 0
+
+    if sysname == "darwin":
+        print("\n--apply is not supported on macOS: pf rules live in a file, so applying\n"
+              "them means editing /etc/pf.anchors/agentos by hand. Follow the note above.")
+        return 1
+
+    ok, tool = _tool_present()
+    if not ok:
+        print(f"\nerror: {tool}")
+        return 1
+    if not _is_privileged():
+        who = "Administrator" if sysname == "windows" else "root (sudo)"
+        print(f"\nerror: --apply needs {who}.")
+        return 1
+
+    failed = 0
+    print()
+    for r in rules:
+        # The printed form carries `sudo` for humans; we are already privileged.
+        cmd = r[len("sudo "):] if r.startswith("sudo ") else r
+        try:
+            proc = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=30)
+        except Exception as exc:  # noqa: BLE001 — never leave the firewall half-known
+            print(f"  ✗ {cmd}\n      {exc}")
+            failed += 1
+            continue
+        tail = (proc.stdout or proc.stderr or "").strip().splitlines()
+        note = tail[-1][:100] if tail else ""
+        if proc.returncode == 0:
+            print(f"  ✓ {cmd}\n      {note}" if note else f"  ✓ {cmd}")
+        else:
+            print(f"  ✗ {cmd}  (exit {proc.returncode})\n      {note}")
+            failed += 1
+
+    print(f"\n{len(rules) - failed}/{len(rules)} applied.")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(cli(sys.argv[1:]))