hypdmz 0.1.0a1__tar.gz

hypdmz-0.1.0a1/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: hypdmz
+Version: 0.1.0a1
+Summary: Run a HypSwarm research swarm inside a governed-egress pod: a UID-scoped egress floor, an allowlisting TLS-intercepting proxy, vaulted credentials, hourly caps, a hash-chained audit — and an egress check from the swarm's own seat on every start.
+Project-URL: Homepage, https://hypdmz.com
+Project-URL: HypSwarm, https://hypswarm.com
+Project-URL: HypGraph, https://hypgraph.com
+Keywords: agents,sandbox,egress,podman,hypswarm,hypgraph,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+
+# HypDMZ
+
+Run a [HypSwarm](https://hypswarm.com) research swarm inside a governed-egress pod. The swarm's models, tools
+and code run in a container that can reach exactly one thing: a proxy that allows the model API and nothing
+else, holds the API key the swarm never sees, decrypts every request to check it, caps what leaves per hour,
+and writes a tamper-evident log of all of it. The record the swarm builds is served live in the
+[HypGraph](https://hypgraph.com) UI. Every start ends with the swarm trying to escape, from its own seat, and the
+pod refusing to run if it can. [hypdmz.com](https://hypdmz.com) shows the measures and the proof.
+
+```
+hypdmz-pod  (one Podman pod, one network namespace)
+├── hypdmz-controller   NET_ADMIN · applies the UID-scoped iptables/ip6tables egress floor · lockdown gate on :8009
+├── hypdmz-proxy        :8080 allowlisting TLS-intercepting forward proxy · :8002 control API · vault · audit chain · hourly caps
+└── hypdmz-swarm        :8000 HypGraph UI on the record · `hypswarm` runs here as UID 1000: loopback only, read-only root, capped
+```
+
+**The egress floor is keyed on socket owner UID, not port.** Only the proxy's UID (1001) may dial out. Every
+other UID — the swarm, anything it spawns — gets loopback only, over IPv4 and IPv6, and cannot reach the
+proxy's control port. The controller applies the rules before anything else starts, publishes `LOCKED` on
+`127.0.0.1:8009`, and re-verifies the rule fingerprint every 30 s. The swarm container refuses to start until
+the gate says `LOCKED`. `hypdmz up` ends by running `egress-check` from the swarm's own seat and stops the
+swarm if any escape probe succeeds.
+
+## Quick start
+
+Needs Podman on the host (Podman Desktop on Windows and macOS, `podman` on Linux) and Python 3.9+. The launcher
+has no dependencies; the three image build contexts, the default policy and an example ride inside the package.
+
+```bash
+pip install hypdmz
+hypdmz init                                  # the state dir and its .env; prints what comes next
+podman secret create hypdmz_llm_api_key -    # paste the model API key; it reaches the proxy only, as a file
+hypdmz doctor
+hypdmz build                                 # three images, from the package's own contexts
+hypdmz up                                    # creates the CA, starts the pod, vaults the key, verifies the egress floor
+hypdmz run first-swarm --python --budget-usd 0.20
+```
+
+Then open http://127.0.0.1:8000 — the record, live, with the swarm's lanes. `hypdmz status`, `hypdmz logs`,
+`hypdmz egress-check`, `hypdmz down`.
+
+`hypdmz run <folder>` copies a folder (a `task.toml`, optional `seats.toml`, data files) into the pod and runs
+`hypswarm run` there as the swarm user; a bundled example's name works too (`hypdmz example` lists them,
+`hypdmz example first-swarm ./mine` copies one out to edit). `--python` gives the seats a Python tool inside the
+locked container. `--profile scientific|software|trading|knowledge|optimization` uses HypSwarm's rosters instead
+of `seats.toml`. Every run is an investigation in the served record (`records/swarm.hypgraph` in the state dir);
+`--record NAME` writes a separate file instead.
+
+## What the swarm can and cannot do
+
+| | |
+|---|---|
+| Reach the model API | yes — through the proxy, `MODEL_BASE_URL`'s host only, inference paths only (`hypdmz policy`) |
+| See the API key | no — it sends a placeholder; the proxy's vault (AES-256-GCM, master key in `proxy-data/`) adds the real one, scoped to the model host. The key arrives as a podman secret mounted into the proxy alone (mode 0400, proxy UID), never in an environment |
+| Reach any other host, by name, by IP, over IPv6, via DNS | no — iptables owner match, verified by `egress-check` |
+| Reach the proxy's control API | no — `:8002` is open to root and the proxy UID only; from the host it needs a bearer token |
+| Read the TLS interception CA's private key | no — the swarm mounts the certificate alone |
+| Rewrite its own code | no — root-owned, `go-w`, checked with `access(2)` as the swarm user at start |
+| Send a secret out in a request | no — DLP over bodies and auth headers blocks it (`DLP_MODE=block`) |
+| Call the model without limit | no — the proxy caps forwarded calls and request megabytes per sliding hour (`limits` in the policy; 429 past the cap, audited) |
+| Exhaust the machine | no — read-only root filesystem, size-capped `/tmp` and home, memory, CPU and process-count limits on the container; only `/records` and `/work` persist |
+| Do anything unlogged | no — every request, allowed or denied, is a line in a SHA-256 hash chain (`proxy-data/audit/`); optional remote sink |
+
+## The policy is a file
+
+`hypdmz up` seeds `<state dir>/policy/firewall.json` from the package's default on the first run; after that it is
+yours. The proxy hot-reloads it (size + mtime, checked once a second). A missing or malformed file denies
+everything. Rules carry host, ports, methods, path prefixes, an optional `guard: "public_web"` request-shape gate,
+`expires_at`, and the vault credential names to inject; `limits` holds the hourly caps. `hypdmz policy` shows it,
+`hypdmz policy path` says where it is, `hypdmz policy reset` restores the default (keeping a `.bak`).
+
+## Layout
+
+```
+hypdmz/                the launcher (stdlib only): init · doctor · build · up · down · status · logs · debug · egress-check · run · policy · example
+hypdmz/images/         the three build contexts, shipped in the wheel: controller (egress floor), proxy, swarm
+hypdmz/images/proxy/config/firewall.json   the default policy
+hypdmz/examples/       first-swarm — a two-seat t-test with the python instrument
+hypdmz/env.example     the .env template `hypdmz init` writes
+tests/                 the launcher without podman (configuration, payload, policy seed, the command lines it would run)
+docs/DESIGN.md         what was taken from PegasusDMZ, what was left out, the blast radius, the limits
+```
+
+State (secrets, policy, records) lives outside the package and outside any repository: `%USERPROFILE%\.hypdmz` on
+Windows, `~/.local/state/hypdmz` on Linux, `~/Library/Application Support/HypDMZ` on macOS (`HYPDMZ_STATE_DIR`
+overrides). `.env` keys: `MODEL_BASE_URL`, `MODEL`, `HYPDMZ_UI_PORT` / `HYPDMZ_CONSOLE_PORT` / `HYPDMZ_PROXY_PORT`,
+`HYPDMZ_SWARM_MEMORY` / `_CPUS` / `_PIDS` / `_TMP`, `HYPDMZ_KEY_SECRET`, `HYPDMZ_RECORDS_DIR`, `DLP_MODE`,
+`AUDIT_SINK_URL` / `AUDIT_SINK_TOKEN`.
+
+## Control API (`:8002`, loopback only, bearer token)
+
+`GET /healthz` · `GET /api/status` · `GET /api/policy` · `GET /api/audit?n=` · `GET /api/audit/verify` ·
+`GET /api/vault` · `POST /api/vault` `{name, value, type, injection_spec?, scope_host?}` · `DELETE /api/vault/{name}`.
+Everything but `/healthz` needs `Authorization: Bearer <token>`; the token is generated once into
+`<state dir>/tokens/console.token` (0600) and mounted read-only into the proxy. `hypdmz status` prints the
+`curl` line. A `Host` header that is not loopback, or a cross-origin state change, is refused as well.
+
+## Using the pod's proxy from the host
+
+The proxy is published on `127.0.0.1:8080` (`HYPDMZ_PROXY_PORT`). Host tools get the same governance:
+
+```
+HTTPS_PROXY=http://127.0.0.1:8080  SSL_CERT_FILE=<state dir>/certs/public/hypdmz-ca-cert.pem  OPENAI_API_KEY=__hypdmz_inject__
+```
+
+## Status
+
+Alpha, private beta. Verified on Windows 11 (Podman Desktop, WSL2); the Linux and macOS paths are written and
+untested. Known limits are on [hypdmz.com](https://hypdmz.com#limits) and in `docs/DESIGN.md`.

hypdmz-0.1.0a1/README.md

@@ -0,0 +1,109 @@
+# HypDMZ
+
+Run a [HypSwarm](https://hypswarm.com) research swarm inside a governed-egress pod. The swarm's models, tools
+and code run in a container that can reach exactly one thing: a proxy that allows the model API and nothing
+else, holds the API key the swarm never sees, decrypts every request to check it, caps what leaves per hour,
+and writes a tamper-evident log of all of it. The record the swarm builds is served live in the
+[HypGraph](https://hypgraph.com) UI. Every start ends with the swarm trying to escape, from its own seat, and the
+pod refusing to run if it can. [hypdmz.com](https://hypdmz.com) shows the measures and the proof.
+
+```
+hypdmz-pod  (one Podman pod, one network namespace)
+├── hypdmz-controller   NET_ADMIN · applies the UID-scoped iptables/ip6tables egress floor · lockdown gate on :8009
+├── hypdmz-proxy        :8080 allowlisting TLS-intercepting forward proxy · :8002 control API · vault · audit chain · hourly caps
+└── hypdmz-swarm        :8000 HypGraph UI on the record · `hypswarm` runs here as UID 1000: loopback only, read-only root, capped
+```
+
+**The egress floor is keyed on socket owner UID, not port.** Only the proxy's UID (1001) may dial out. Every
+other UID — the swarm, anything it spawns — gets loopback only, over IPv4 and IPv6, and cannot reach the
+proxy's control port. The controller applies the rules before anything else starts, publishes `LOCKED` on
+`127.0.0.1:8009`, and re-verifies the rule fingerprint every 30 s. The swarm container refuses to start until
+the gate says `LOCKED`. `hypdmz up` ends by running `egress-check` from the swarm's own seat and stops the
+swarm if any escape probe succeeds.
+
+## Quick start
+
+Needs Podman on the host (Podman Desktop on Windows and macOS, `podman` on Linux) and Python 3.9+. The launcher
+has no dependencies; the three image build contexts, the default policy and an example ride inside the package.
+
+```bash
+pip install hypdmz
+hypdmz init                                  # the state dir and its .env; prints what comes next
+podman secret create hypdmz_llm_api_key -    # paste the model API key; it reaches the proxy only, as a file
+hypdmz doctor
+hypdmz build                                 # three images, from the package's own contexts
+hypdmz up                                    # creates the CA, starts the pod, vaults the key, verifies the egress floor
+hypdmz run first-swarm --python --budget-usd 0.20
+```
+
+Then open http://127.0.0.1:8000 — the record, live, with the swarm's lanes. `hypdmz status`, `hypdmz logs`,
+`hypdmz egress-check`, `hypdmz down`.
+
+`hypdmz run <folder>` copies a folder (a `task.toml`, optional `seats.toml`, data files) into the pod and runs
+`hypswarm run` there as the swarm user; a bundled example's name works too (`hypdmz example` lists them,
+`hypdmz example first-swarm ./mine` copies one out to edit). `--python` gives the seats a Python tool inside the
+locked container. `--profile scientific|software|trading|knowledge|optimization` uses HypSwarm's rosters instead
+of `seats.toml`. Every run is an investigation in the served record (`records/swarm.hypgraph` in the state dir);
+`--record NAME` writes a separate file instead.
+
+## What the swarm can and cannot do
+
+| | |
+|---|---|
+| Reach the model API | yes — through the proxy, `MODEL_BASE_URL`'s host only, inference paths only (`hypdmz policy`) |
+| See the API key | no — it sends a placeholder; the proxy's vault (AES-256-GCM, master key in `proxy-data/`) adds the real one, scoped to the model host. The key arrives as a podman secret mounted into the proxy alone (mode 0400, proxy UID), never in an environment |
+| Reach any other host, by name, by IP, over IPv6, via DNS | no — iptables owner match, verified by `egress-check` |
+| Reach the proxy's control API | no — `:8002` is open to root and the proxy UID only; from the host it needs a bearer token |
+| Read the TLS interception CA's private key | no — the swarm mounts the certificate alone |
+| Rewrite its own code | no — root-owned, `go-w`, checked with `access(2)` as the swarm user at start |
+| Send a secret out in a request | no — DLP over bodies and auth headers blocks it (`DLP_MODE=block`) |
+| Call the model without limit | no — the proxy caps forwarded calls and request megabytes per sliding hour (`limits` in the policy; 429 past the cap, audited) |
+| Exhaust the machine | no — read-only root filesystem, size-capped `/tmp` and home, memory, CPU and process-count limits on the container; only `/records` and `/work` persist |
+| Do anything unlogged | no — every request, allowed or denied, is a line in a SHA-256 hash chain (`proxy-data/audit/`); optional remote sink |
+
+## The policy is a file
+
+`hypdmz up` seeds `<state dir>/policy/firewall.json` from the package's default on the first run; after that it is
+yours. The proxy hot-reloads it (size + mtime, checked once a second). A missing or malformed file denies
+everything. Rules carry host, ports, methods, path prefixes, an optional `guard: "public_web"` request-shape gate,
+`expires_at`, and the vault credential names to inject; `limits` holds the hourly caps. `hypdmz policy` shows it,
+`hypdmz policy path` says where it is, `hypdmz policy reset` restores the default (keeping a `.bak`).
+
+## Layout
+
+```
+hypdmz/                the launcher (stdlib only): init · doctor · build · up · down · status · logs · debug · egress-check · run · policy · example
+hypdmz/images/         the three build contexts, shipped in the wheel: controller (egress floor), proxy, swarm
+hypdmz/images/proxy/config/firewall.json   the default policy
+hypdmz/examples/       first-swarm — a two-seat t-test with the python instrument
+hypdmz/env.example     the .env template `hypdmz init` writes
+tests/                 the launcher without podman (configuration, payload, policy seed, the command lines it would run)
+docs/DESIGN.md         what was taken from PegasusDMZ, what was left out, the blast radius, the limits
+```
+
+State (secrets, policy, records) lives outside the package and outside any repository: `%USERPROFILE%\.hypdmz` on
+Windows, `~/.local/state/hypdmz` on Linux, `~/Library/Application Support/HypDMZ` on macOS (`HYPDMZ_STATE_DIR`
+overrides). `.env` keys: `MODEL_BASE_URL`, `MODEL`, `HYPDMZ_UI_PORT` / `HYPDMZ_CONSOLE_PORT` / `HYPDMZ_PROXY_PORT`,
+`HYPDMZ_SWARM_MEMORY` / `_CPUS` / `_PIDS` / `_TMP`, `HYPDMZ_KEY_SECRET`, `HYPDMZ_RECORDS_DIR`, `DLP_MODE`,
+`AUDIT_SINK_URL` / `AUDIT_SINK_TOKEN`.
+
+## Control API (`:8002`, loopback only, bearer token)
+
+`GET /healthz` · `GET /api/status` · `GET /api/policy` · `GET /api/audit?n=` · `GET /api/audit/verify` ·
+`GET /api/vault` · `POST /api/vault` `{name, value, type, injection_spec?, scope_host?}` · `DELETE /api/vault/{name}`.
+Everything but `/healthz` needs `Authorization: Bearer <token>`; the token is generated once into
+`<state dir>/tokens/console.token` (0600) and mounted read-only into the proxy. `hypdmz status` prints the
+`curl` line. A `Host` header that is not loopback, or a cross-origin state change, is refused as well.
+
+## Using the pod's proxy from the host
+
+The proxy is published on `127.0.0.1:8080` (`HYPDMZ_PROXY_PORT`). Host tools get the same governance:
+
+```
+HTTPS_PROXY=http://127.0.0.1:8080  SSL_CERT_FILE=<state dir>/certs/public/hypdmz-ca-cert.pem  OPENAI_API_KEY=__hypdmz_inject__
+```
+
+## Status
+
+Alpha, private beta. Verified on Windows 11 (Podman Desktop, WSL2); the Linux and macOS paths are written and
+untested. Known limits are on [hypdmz.com](https://hypdmz.com#limits) and in `docs/DESIGN.md`.

hypdmz-0.1.0a1/hypdmz/__init__.py

@@ -0,0 +1,3 @@
+"""HypDMZ — run a HypSwarm research swarm inside a governed-egress pod."""
+
+__version__ = "0.1.0a1"

hypdmz-0.1.0a1/hypdmz/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from hypdmz.cli import main
+
+sys.exit(main())

hypdmz-0.1.0a1/hypdmz/cli.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+
+from hypdmz import __version__
+from hypdmz.doctor import cmd_doctor
+from hypdmz.egress import cmd_egress_check
+from hypdmz.env import Config, load
+from hypdmz.platforms import detect
+from hypdmz.runner import bundled_examples, cmd_build, cmd_debug, cmd_down, cmd_logs, cmd_run, cmd_up, ensure_policy
+from hypdmz.status import cmd_status
+
+
+def cmd_init(cfg: Config) -> int:
+    """Create the state directory and its .env from the package's template; say what comes next."""
+    cfg.state_dir.mkdir(parents=True, exist_ok=True)
+    if cfg.env_file.exists():
+        print(f"[hypdmz] .env already there: {cfg.env_file}")
+    else:
+        shutil.copyfile(cfg.env_example, cfg.env_file)
+        print(f"[hypdmz] wrote {cfg.env_file}")
+    created = ensure_policy(cfg)
+    if not created:
+        print(f"[hypdmz] policy already there: {cfg.policy_path}")
+    print(f"""
+[hypdmz] next:
+  1. edit {cfg.env_file}: MODEL_BASE_URL and MODEL (DeepInfra is the default)
+  2. put the model API key in a podman secret:   podman secret create {cfg.key_secret} -
+     (paste the key, Enter, then Ctrl-D on Linux/macOS or Ctrl-Z Enter on Windows)
+  3. hypdmz doctor · hypdmz build · hypdmz up · hypdmz run first-swarm --python --budget-usd 0.20
+  the allowlist is {cfg.policy_path} (hot-reloaded; `hypdmz policy reset` restores the default)""")
+    return 0
+
+
+def cmd_policy(cfg: Config, action: str) -> int:
+    if action == "path":
+        print(cfg.policy_path)
+        return 0
+    if action == "reset":
+        cfg.policy_dir.mkdir(parents=True, exist_ok=True)
+        if cfg.policy_path.exists():
+            backup = cfg.policy_path.with_suffix(".json.bak")
+            shutil.copyfile(cfg.policy_path, backup)
+            print(f"[hypdmz] previous policy kept at {backup}")
+        shutil.copyfile(cfg.default_policy, cfg.policy_path)
+        print(f"[hypdmz] policy reset to the package default → {cfg.policy_path} (the proxy picks it up within a second)")
+        return 0
+    # show
+    src = cfg.policy_path if cfg.policy_path.exists() else cfg.default_policy
+    try:
+        pol = json.loads(src.read_text(encoding="utf-8"))
+    except Exception as e:
+        print(f"[hypdmz] {src} does not parse ({e}) — the proxy denies everything until it does")
+        return 1
+    print(f"[hypdmz] {src}{'' if src == cfg.policy_path else '  (package default; no operator policy yet)'}")
+    lim = pol.get("limits") or {}
+    print(f"  limits: {lim.get('calls_per_hour') or '∞'} calls/h · {lim.get('megabytes_per_hour') or '∞'} MB/h")
+    for c in pol.get("cidr_blocklist") or []:
+        print(f"  block   {c.get('name')}: {', '.join(c.get('cidrs') or [])}")
+    for r in pol.get("rules") or []:
+        hosts = r.get("host") or ", ".join(r.get("hosts") or r.get("host_suffixes") or []) or r.get("host_regex") or "*"
+        flag = "" if r.get("enabled", True) else "  (disabled)"
+        guard = f"  guard={r['guard']}" if r.get("guard") else ""
+        exp = f"  until {r['expires_at']}" if r.get("expires_at") else ""
+        print(f"  rule    {r.get('name')}: {r.get('scheme', 'https')}://{hosts} {r.get('ports') or ''} "
+              f"{'/'.join(r.get('methods') or ['*'])} {' '.join(r.get('path_prefixes') or ['/'])}"
+              f"{'  injects ' + ','.join(r['injects']) if r.get('injects') else ''}{guard}{exp}{flag}")
+    return 0
+
+
+def cmd_examples(cfg: Config, name: str, dest: Path | None) -> int:
+    names = bundled_examples(cfg)
+    if not name:
+        for n in names:
+            print(n)
+        return 0
+    if name not in names:
+        print(f"[hypdmz] no bundled example '{name}' (have: {', '.join(names)})")
+        return 2
+    target = (dest or Path(name)).resolve()
+    if target.exists():
+        print(f"[hypdmz] {target} exists")
+        return 2
+    shutil.copytree(cfg.examples_dir / name, target)
+    print(f"[hypdmz] copied {name} → {target}  (edit task.toml and seats.toml, then: hypdmz run {target})")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")   # Windows consoles default to cp1252
+    p = argparse.ArgumentParser(prog="hypdmz", description="Run a HypSwarm research swarm inside a governed-egress pod.")
+    p.add_argument("--version", action="version", version=f"hypdmz {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("init", help="create the state dir and .env; print what comes next")
+    s = sub.add_parser("doctor", help="preflight checks"); s.add_argument("--json", action="store_true")
+    s = sub.add_parser("build", help="build the three images from the package's contexts"); s.add_argument("--dry-run", action="store_true")
+    s = sub.add_parser("up", help="create the pod, start the containers, verify the egress floor")
+    s.add_argument("--dry-run", action="store_true"); s.add_argument("--skip-egress-check", action="store_true")
+    sub.add_parser("down", help="stop and remove the pod")
+    s = sub.add_parser("status", help="pod, lockdown and endpoint snapshot"); s.add_argument("--json", action="store_true")
+    s = sub.add_parser("logs", help="tail the containers"); s.add_argument("--no-follow", action="store_true")
+    sub.add_parser("debug", help="pod, lockdown state and iptables view")
+    s = sub.add_parser("egress-check", help="escape attempts as the swarm user; exit 1 on any bypass")
+    s.add_argument("--json", action="store_true")
+    s = sub.add_parser("run", help="run a swarm: a folder with task.toml (and seats.toml or --profile), or a bundled example's name")
+    s.add_argument("folder", type=Path)
+    s.add_argument("--task", default="task.toml"); s.add_argument("--seats", default="")
+    s.add_argument("--profile", default="", help="scientific | software | trading | knowledge | optimization")
+    s.add_argument("--model", default="", help="default model id (else MODEL from .env)")
+    s.add_argument("--budget-usd", type=float, default=0.0); s.add_argument("--budget-calls", type=int, default=150)
+    s.add_argument("--pricing", default="", help="input,cached,output $ per million tokens")
+    s.add_argument("--python", action="store_true", help="give the seats a python tool in the work folder (in the pod)")
+    s.add_argument("--record", default="", help="record file name under records/ (default: the served swarm.hypgraph)")
+    s.add_argument("--name", default="", help="name for this run's work folder")
+    s = sub.add_parser("policy", help="the egress allowlist: show, path, reset")
+    s.add_argument("action", nargs="?", default="show", choices=["show", "path", "reset"])
+    s = sub.add_parser("example", help="list the bundled examples, or copy one out to edit")
+    s.add_argument("name", nargs="?", default=""); s.add_argument("dest", nargs="?", type=Path, default=None)
+
+    a = p.parse_args(argv)
+    cfg = load()
+    try:
+        if a.cmd == "init":
+            return cmd_init(cfg)
+        if a.cmd == "policy":
+            return cmd_policy(cfg, a.action)
+        if a.cmd == "example":
+            return cmd_examples(cfg, a.name, a.dest)
+        platform = detect()
+        if a.cmd == "doctor":
+            return cmd_doctor(cfg, platform, json_output=a.json)
+        if a.cmd == "build":
+            return cmd_build(cfg, platform, dry_run=a.dry_run)
+        if a.cmd == "up":
+            return cmd_up(cfg, platform, dry_run=a.dry_run, skip_egress_check=a.skip_egress_check)
+        if a.cmd == "down":
+            return cmd_down(cfg, platform)
+        if a.cmd == "status":
+            return cmd_status(cfg, platform, json_output=a.json)
+        if a.cmd == "logs":
+            return cmd_logs(cfg, platform, follow=not a.no_follow)
+        if a.cmd == "debug":
+            return cmd_debug(cfg, platform)
+        if a.cmd == "egress-check":
+            return cmd_egress_check(cfg, platform, json_output=a.json)
+        if a.cmd == "run":
+            return cmd_run(cfg, platform, a.folder, task=a.task, seats=a.seats, profile=a.profile, model=a.model,
+                           budget_usd=a.budget_usd, budget_calls=a.budget_calls, pricing=a.pricing,
+                           python=a.python, record=a.record, name=a.name)
+    except KeyboardInterrupt:
+        return 130
+    except RuntimeError as e:
+        print(f"[hypdmz] {e}", file=sys.stderr)
+        return 1
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hypdmz-0.1.0a1/hypdmz/doctor.py

@@ -0,0 +1,76 @@
+"""`hypdmz doctor` — preflight checks before the first `up`."""
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+
+from hypdmz.env import Config, sync_folder_marker
+from hypdmz.platforms.base import Platform, PreflightResult
+
+
+def cmd_doctor(cfg: Config, platform: Platform, *, json_output: bool = False) -> int:
+    app_results = [_check_env_file(cfg), _check_state_dir(cfg), _check_model_key(cfg), _check_package(cfg), _check_policy(cfg)]
+    plat_results = platform.preflight()
+    fail = sum(1 for r in app_results + plat_results if not r.ok)
+    if json_output:
+        print(json.dumps({"platform": platform.name, "ok": fail == 0, "fail_count": fail,
+                          "application": [asdict(r) for r in app_results],
+                          "platform_checks": [asdict(r) for r in plat_results]}, indent=2))
+        return 0 if fail == 0 else 1
+    print(f"[hypdmz] doctor — platform={platform.name}\n")
+    for r in app_results:
+        print(r.render())
+    print("\n── platform checks ──")
+    for r in plat_results:
+        print(r.render())
+    print()
+    print("[hypdmz] all checks passed." if fail == 0 else f"[hypdmz] {fail} check(s) failed.")
+    return 0 if fail == 0 else 1
+
+
+def _check_env_file(cfg: Config) -> PreflightResult:
+    if cfg.env_file.exists():
+        return PreflightResult(".env present", True, str(cfg.env_file))
+    return PreflightResult(".env present", False, f"run `hypdmz init` (writes {cfg.env_file} from the package template)")
+
+
+def _check_state_dir(cfg: Config) -> PreflightResult:
+    marker = sync_folder_marker(cfg.state_dir)
+    if marker:
+        return PreflightResult("state dir is local", False,
+                               f"{cfg.state_dir} is under a cloud-synced folder ({marker}); set HYPDMZ_STATE_DIR")
+    return PreflightResult("state dir is local", True, str(cfg.state_dir))
+
+
+def _check_model_key(cfg: Config) -> PreflightResult:
+    from hypdmz.runner import secret_exists
+
+    vault = cfg.proxy_data_dir / "vault.db"
+    if secret_exists(cfg.key_secret):
+        return PreflightResult("model API key", True, f"podman secret '{cfg.key_secret}' (mounted into the proxy only)")
+    if cfg.model_api_key:
+        return PreflightResult("model API key", True, "MODEL_API_KEY in .env; vaulted on the next `up` — then delete the "
+                               f"line (better: podman secret create {cfg.key_secret} -)")
+    if vault.exists():
+        return PreflightResult("model API key", True, "no secret, not in .env; the vault exists (hypdmz status shows the count)")
+    return PreflightResult("model API key", False,
+                           f"no key: `podman secret create {cfg.key_secret} -` (paste it), or MODEL_API_KEY in .env")
+
+
+def _check_package(cfg: Config) -> PreflightResult:
+    missing = [p for p in ("controller/Dockerfile", "proxy/Dockerfile", "swarm/Dockerfile", "proxy/config/firewall.json")
+               if not (cfg.images_dir / p).exists()]
+    if missing:
+        return PreflightResult("bundled images", False, f"missing under {cfg.images_dir}: {', '.join(missing)} (broken install?)")
+    return PreflightResult("bundled images", True, f"{cfg.images_dir} (controller, proxy, swarm)")
+
+
+def _check_policy(cfg: Config) -> PreflightResult:
+    src = cfg.policy_path if cfg.policy_path.exists() else cfg.default_policy
+    try:
+        pol = json.loads(src.read_text(encoding="utf-8"))
+        n = len(pol.get("rules") or [])
+    except Exception as e:
+        return PreflightResult("egress policy", False, f"{src} does not parse ({e}); the proxy denies everything until it does")
+    where = "operator policy" if src == cfg.policy_path else "package default (seeded on the first `up`)"
+    return PreflightResult("egress policy", True, f"{src}: {n} rule(s), {where}")