haze-agent 0.1.0__tar.gz

haze_agent-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# --- Python -----------------------------------------------------------------
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# --- Node -------------------------------------------------------------------
+node_modules/
+web/dist/
+*.tsbuildinfo
+
+# --- The bundled dashboard --------------------------------------------------
+# `web/` is built into the Python wheel at package time (see agent/pyproject.toml
+# [tool.hatch.build.force-include]).  The copy that lands here is a build
+# artifact, never a source file -- committing it would mean two sources of truth
+# for the dashboard and a guaranteed drift bug.
+agent/src/haze/webui/
+
+# --- Local agent state ------------------------------------------------------
+# Contains the Ed25519 identity seed and the dashboard bearer token.  Never
+# commit; see SECURITY.md.
+.haze/
+*.db
+*.db-journal
+
+# --- Secrets ----------------------------------------------------------------
+.env
+.env.*
+!.env.example
+!.env.production
+
+# --- macOS ------------------------------------------------------------------
+.DS_Store
+
+# Firebase CLI deploy cache — local only, machine-specific hashes.
+.firebase/

haze_agent-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: haze-agent
+Version: 0.1.0
+Summary: Haze -- pool your own machines into a private compute network
+Project-URL: Homepage, https://github.com/CodeMaster747/Haze
+Project-URL: Repository, https://github.com/CodeMaster747/Haze
+Author: Rahul Akshath
+License: MIT
+Keywords: distributed-computing,lan,resource-sharing,self-hosted
+Requires-Python: <3.14,>=3.12
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: cryptography>=50.0.1
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: psutil>=6.1.0
+Requires-Dist: pydantic-settings>=2.6.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.36
+Requires-Dist: typer>=0.15.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Requires-Dist: zeroconf>=0.150.3
+Provides-Extra: dev
+Requires-Dist: httpx2>=2.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: types-psutil>=6.1.0; extra == 'dev'
+Provides-Extra: nvidia
+Requires-Dist: nvidia-ml-py>=12.560.30; extra == 'nvidia'
+Description-Content-Type: text/markdown
+
+# Haze — Node Agent
+
+Pool your own machines into a private compute network. A weak laptop borrows a
+desktop's GPU; a NAS lends its disks. You own every node, so there is no cloud
+bill and no third party in the data path.
+
+This package is the **Node Agent**: the process that runs on each machine. It
+serves the Haze dashboard on `http://127.0.0.1:7433`, discovers and pairs with
+your other machines over the LAN, reports live resources, and executes jobs
+within limits you set.
+
+## Install
+
+```bash
+uv tool install haze-agent     # or: pipx install haze-agent
+haze up
+```
+
+The distribution is `haze-agent`; the command it installs is `haze`.
+
+## Try it on one machine
+
+```bash
+haze devnet up -n 4 --open     # four agents with simulated hardware profiles
+```
+
+## Why the dashboard is served locally
+
+A public HTTPS page can no longer reach a local agent: Safari hard-blocks it as
+mixed content, and Chrome 142+ gates it behind a Local Network Access prompt
+that Chrome 147 extended to WebSockets. Serving the UI from the agent's own
+origin sidesteps all of it — the same choice Syncthing, Jellyfin, Home Assistant
+and Ollama make.
+
+Full documentation, architecture notes and the live demo:
+**https://github.com/CodeMaster747/Haze**
+
+MIT licensed.

haze_agent-0.1.0/README.md

@@ -0,0 +1,38 @@
+# Haze — Node Agent
+
+Pool your own machines into a private compute network. A weak laptop borrows a
+desktop's GPU; a NAS lends its disks. You own every node, so there is no cloud
+bill and no third party in the data path.
+
+This package is the **Node Agent**: the process that runs on each machine. It
+serves the Haze dashboard on `http://127.0.0.1:7433`, discovers and pairs with
+your other machines over the LAN, reports live resources, and executes jobs
+within limits you set.
+
+## Install
+
+```bash
+uv tool install haze-agent     # or: pipx install haze-agent
+haze up
+```
+
+The distribution is `haze-agent`; the command it installs is `haze`.
+
+## Try it on one machine
+
+```bash
+haze devnet up -n 4 --open     # four agents with simulated hardware profiles
+```
+
+## Why the dashboard is served locally
+
+A public HTTPS page can no longer reach a local agent: Safari hard-blocks it as
+mixed content, and Chrome 142+ gates it behind a Local Network Access prompt
+that Chrome 147 extended to WebSockets. Serving the UI from the agent's own
+origin sidesteps all of it — the same choice Syncthing, Jellyfin, Home Assistant
+and Ollama make.
+
+Full documentation, architecture notes and the live demo:
+**https://github.com/CodeMaster747/Haze**
+
+MIT licensed.

haze_agent-0.1.0/pyproject.toml

@@ -0,0 +1,152 @@
+# Haze Node Agent -- the process that runs on every machine in the network.
+#
+# Distribution name is `haze-agent`, not `haze`: the `haze` name is already
+# taken on PyPI (verified 2026-08-29, HTTP 200).  The CLI command is still
+# `haze` -- console-script names are independent of the distribution name, so
+# `uv tool install haze-agent` gives you a `haze` binary.
+
+[project]
+name = "haze-agent"
+version = "0.1.0"
+description = "Haze -- pool your own machines into a private compute network"
+readme = "README.md"
+requires-python = ">=3.12,<3.14"
+license = { text = "MIT" }
+authors = [{ name = "Rahul Akshath" }]
+keywords = ["distributed-computing", "resource-sharing", "lan", "self-hosted"]
+
+dependencies = [
+    # The loopback dashboard API.  Bound to 127.0.0.1 only -- see api/app.py for
+    # why that binding is load-bearing rather than a default.
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.32.0",
+    "pydantic>=2.9.0",
+    "pydantic-settings>=2.6.0",
+    # CLI.  typer rather than click directly: the `haze devnet up -n 4` style
+    # subcommand tree is what typer is good at, and it is click underneath.
+    "typer>=0.15.0",
+    # Identity + TLS certificates (M1).  One audited dependency covers Ed25519,
+    # X.509 generation and HKDF, which is why PyNaCl is deliberately absent --
+    # we never need the Ed25519->X25519 conversion that only PyNaCl exposes,
+    # because TLS 1.3 negotiates its own ephemeral X25519 inside the handshake.
+    "cryptography>=50.0.1",
+    # mDNS/DNS-SD discovery (M2).  Effectively maintained by the Home Assistant
+    # core team; does NOT use D-Bus, so it works on a NAS with no Avahi.
+    "zeroconf>=0.150.3",
+    # Resource probing (M2).  Per-core CPU, RAM, disk, network counters.
+    "psutil>=6.1.0",
+    # Local state: paired peers, jobs, caps.  aiosqlite because the API layer is
+    # async and a blocking sqlite3 call would stall the telemetry WebSocket.
+    "sqlalchemy[asyncio]>=2.0.36",
+    "aiosqlite>=0.20.0",
+]
+
+[project.optional-dependencies]
+# NVIDIA telemetry.  An extra, not a core dependency: the package pulls CUDA
+# metadata and is useless on the ~half of plausible Haze nodes that are Macs or
+# AMD boxes.  probe/gpu_nvidia.py imports it lazily and degrades to "no GPU".
+nvidia = ["nvidia-ml-py>=12.560.30"]
+
+dev = [
+    "pytest>=8.3.0",
+    "pytest-asyncio>=0.24.0",
+    # Starlette's TestClient transport. httpx2, not httpx: starlette warns on
+    # every import that the httpx 0.x backend is deprecated.
+    "httpx2>=2.12.0",
+    "ruff>=0.8.0",
+    "mypy>=1.13.0",
+    # psutil ships no py.typed; without stubs mypy strict fails on every probe.
+    "types-psutil>=6.1.0",
+]
+
+[project.scripts]
+haze = "haze.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/CodeMaster747/Haze"
+Repository = "https://github.com/CodeMaster747/Haze"
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+# ---------------------------------------------------------------------------
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/haze"]
+# src/haze/webui/ is the built React dashboard, copied in by `make build-web`.
+# It is gitignored (it is a build artifact of web/, not a source of truth), and
+# hatchling honours .gitignore by default -- so without this line the wheel
+# would ship an agent with no UI.  This is the single most breakable line in
+# the file; `make verify-wheel` exists to catch it.
+artifacts = ["src/haze/webui/**"]
+
+# ---------------------------------------------------------------------------
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# `×` in user-facing output ("relative speed ×4.2") is a deliberate
+# typographic choice, as are the dashes and curly quotes. These rules exist
+# to catch a Cyrillic `a` smuggled into an identifier, not to force ASCII on
+# prose a human reads.
+allowed-confusables = ["×", "−", "—", "–", "“", "”", "’", "→", "·"]
+select = [
+    "E", "W",    # pycodestyle
+    "F",         # pyflakes
+    "I",         # isort
+    "N",         # pep8-naming
+    "UP",        # pyupgrade
+    "B",         # bugbear
+    "C4",        # comprehensions
+    "SIM",       # simplify
+    "RUF",       # ruff-specific
+    "ASYNC",     # async correctness -- matters a lot here, the agent is all asyncio
+    "S",         # bandit security -- this project executes subprocesses, so keep it on
+    "DTZ",       # naive datetime usage
+]
+ignore = [
+    "E501",    # line length is the formatter's job
+    "B008",    # FastAPI's Depends() in argument defaults is the framework idiom
+    "S101",    # assert is how pytest works
+]
+
+[tool.ruff.lint.per-file-ignores]
+# S603: the integration test spawns `python -m haze` with a fixed argv.
+# S310: it drives the local agent over a hardcoded http://127.0.0.1 URL.
+# C408: dict(...) reads better than a brace literal for keyword-style test
+# fixtures that are then splatted over with overrides.
+"**/tests/*" = ["S101", "S105", "S106", "S311", "S603", "S310", "S108", "C408"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["haze"]
+
+# ---------------------------------------------------------------------------
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_unreachable = true
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+# Ships no py.typed.  Imported lazily in probe/gpu_nvidia.py behind a try/except.
+module = ["pynvml", "pynvml.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+# ---------------------------------------------------------------------------
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-q --strict-markers"
+markers = [
+    "lan: requires a second real machine on the LAN; skipped in CI",
+]

haze_agent-0.1.0/src/haze/__init__.py

@@ -0,0 +1,8 @@
+"""Haze -- pool your own machines into a private compute network."""
+
+__version__ = "0.1.0"
+
+# Bumped independently of __version__.  Two agents refuse to talk if their
+# PROTOCOL_VERSION differs, so an old node on the LAN fails loudly at the
+# handshake instead of subtly misparsing a frame three messages later.
+PROTOCOL_VERSION = 1

haze_agent-0.1.0/src/haze/__main__.py

@@ -0,0 +1,12 @@
+"""`python -m haze`.
+
+Routes through the same entry point as the `haze` console script, so both
+present recoverable errors the same way. They diverged once: the console script
+was fixed to show a clean message and `python -m haze` still dumped a
+traceback, which the integration tests use and so would have kept passing.
+"""
+
+from haze.cli import main
+
+if __name__ == "__main__":
+    main()

haze_agent-0.1.0/src/haze/api/__init__.py

@@ -0,0 +1 @@
+"""The loopback dashboard API.  Bound to 127.0.0.1 only -- never 0.0.0.0."""

haze_agent-0.1.0/src/haze/api/app.py

@@ -0,0 +1,206 @@
+"""The loopback FastAPI application.
+
+Architecture note -- why the dashboard is served from here rather than from the
+deployed Firebase site:
+
+A public https origin can no longer reach a local agent.  Safari hard-blocks
+https -> http://127.0.0.1 as mixed content with no user override (WebKit bug
+171934, open since 2017).  Chrome 142 (Oct 2025) began prompting for Local
+Network Access on any public-origin request to loopback/RFC1918/.local, and
+Chrome 147 (Apr 2026) extended that gate to WebSockets, closing the one
+remaining workaround.
+
+Same-address-space requests are explicitly exempt.  So the agent serves the SPA
+itself and the browser only ever talks to one origin: http://127.0.0.1:<port>.
+That single decision removes CORS, mixed content, the LNA prompt and certificate
+warnings from the project simultaneously.  It is also what Syncthing (8384),
+Jellyfin (8096), Home Assistant (8123) and Ollama (11434) all do.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, FastAPI
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.staticfiles import StaticFiles
+from starlette.websockets import WebSocket
+
+import haze
+from haze import log, runtime
+from haze.api import routes_jobs, routes_pairing, security, ws
+from haze.config import Config
+
+_log = log.get("api.app")
+
+WEBUI_DIR = Path(__file__).resolve().parent.parent / "webui"
+
+_PLACEHOLDER = """<!doctype html><meta charset=utf-8>
+<title>Haze - dashboard not built</title>
+<style>body{font:15px/1.6 ui-monospace,Menlo,monospace;background:#0b0b0d;color:#f4f4f5;
+padding:3rem;max-width:44rem;margin:auto}code{background:#1a1a1f;padding:.15rem .4rem;
+border-radius:4px}a{color:#7c5cff}</style>
+<h1>Haze agent is running</h1>
+<p>The API is live, but the dashboard bundle has not been built into this
+install yet.</p>
+<p>From the repo root:</p>
+<pre><code>make build-web</code></pre>
+<p>Then restart the agent. The API itself is already usable:
+<code>GET /api/v1/node</code>.</p>
+"""
+
+
+class _SecurityHeaders(BaseHTTPMiddleware):
+    """Headers that matter for a loopback server reachable from any web page.
+
+    Note what is *absent*: there is no CORSMiddleware and no
+    Access-Control-Allow-Origin header anywhere in this app.  That is
+    deliberate.  The dashboard is same-origin, so it needs no CORS grant, and
+    adding one would hand cross-origin read access to exactly the attacker this
+    server has to keep out.
+    """
+
+    async def dispatch(self, request: Request, call_next):  # type: ignore[no-untyped-def]
+        response: Response = await call_next(request)
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["Referrer-Policy"] = "no-referrer"
+        # The token can arrive as ?t=... on the first navigation; keep that URL
+        # out of any shared cache.
+        if request.url.path == "/" or request.url.path.endswith(".html"):
+            response.headers["Cache-Control"] = "no-store"
+        return response
+
+
+def create_app(
+    cfg: Config,
+    api_port: int,
+    *,
+    serve_peers: bool = True,
+    discover: bool = True,
+    profile: str | None = None,
+) -> FastAPI:
+    """Build the loopback app.
+
+    ``serve_peers=False`` skips binding the node-to-node listener, which is what
+    the test suite wants: it exercises the API without claiming a LAN port that
+    a real agent (or a parallel test) might already hold.
+    """
+    security.configure(cfg.dashboard_token, api_port)
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+        agent = await runtime.start(
+            cfg, serve_peers=serve_peers, discover=discover, profile=profile
+        )
+        app.state.agent = agent
+
+        hub = ws.TelemetryHub(agent.probe)
+        await hub.start()
+        app.state.hub = hub
+
+        _log.info("dashboard  %s", f"http://127.0.0.1:{api_port}/")
+        try:
+            yield
+        finally:
+            await hub.stop()
+            await runtime.stop(agent)
+
+    app = FastAPI(
+        title="Haze Node Agent",
+        version=haze.__version__,
+        lifespan=lifespan,
+        # No interactive docs: they are an unauthenticated surface that
+        # enumerates every route for any page that gets past the origin check.
+        docs_url=None,
+        redoc_url=None,
+        openapi_url=None,
+    )
+    app.add_middleware(_SecurityHeaders)
+
+    api = APIRouter(prefix="/api/v1", dependencies=[Depends(security.require_api_auth)])
+
+    @api.get("/health")
+    async def health() -> JSONResponse:
+        return JSONResponse({"ok": True, "version": haze.__version__,
+                             "protocol": haze.PROTOCOL_VERSION})
+
+    @api.get("/node")
+    async def node() -> JSONResponse:
+        """This node's own identity and current state."""
+        hub: ws.TelemetryHub = app.state.hub
+        agent: runtime.Agent | None = getattr(app.state, "agent", None)
+        return JSONResponse(
+            {
+                "name": cfg.node_name,
+                "node_id": agent.node_id if agent else None,
+                "short_id": agent.identity.short_id if agent else None,
+                "simulated": agent.simulated if agent else False,
+                "api_port": api_port,
+                "node_port": cfg.node_port,
+                "version": haze.__version__,
+                "snapshot": hub.latest(),
+            }
+        )
+
+    api.include_router(routes_pairing.router)
+    api.include_router(routes_jobs.router)
+    app.include_router(api)
+
+    @app.websocket("/ws")
+    async def telemetry(socket: WebSocket) -> None:
+        auth = await security.authorise_websocket(socket)
+        if not auth.allowed:
+            return  # authorise_websocket already closed the socket
+        await socket.accept(subprotocol=auth.subprotocol)
+        hub: ws.TelemetryHub = app.state.hub
+        agent: runtime.Agent | None = getattr(app.state, "agent", None)
+        await hub.serve(socket, agent)
+
+    # --- static SPA, mounted last so it never shadows /api or /ws ------------
+    if (WEBUI_DIR / "index.html").is_file():
+        assets = WEBUI_DIR / "assets"
+        if assets.is_dir():
+            app.mount("/assets", StaticFiles(directory=assets), name="assets")
+
+        @app.get("/{path:path}", include_in_schema=False)
+        async def spa(path: str) -> Response:
+            # Serve a real file if one exists (favicon, manifest), otherwise
+            # hand back index.html so client-side routes deep-link correctly.
+            candidate = (WEBUI_DIR / path).resolve()
+            if path and candidate.is_file() and candidate.is_relative_to(WEBUI_DIR):
+                return FileResponse(candidate)
+            return FileResponse(WEBUI_DIR / "index.html")
+    else:
+        _log.warning("dashboard bundle missing at %s -- run `make build-web`", WEBUI_DIR)
+
+        @app.get("/{path:path}", include_in_schema=False)
+        async def placeholder(path: str) -> HTMLResponse:
+            return HTMLResponse(_PLACEHOLDER)
+
+    return app
+
+
+async def serve(cfg: Config, api_port: int, *, profile: str | None = None) -> None:
+    """Run uvicorn bound to the 127.0.0.1 literal."""
+    import uvicorn
+
+    config = uvicorn.Config(
+        create_app(cfg, api_port, profile=profile),
+        # NEVER 0.0.0.0.  This server can execute subprocesses; exposing it to
+        # the LAN would hand that to anyone on the same WiFi.  Node-to-node
+        # traffic uses the mutually-authenticated TLS listener instead.
+        host="127.0.0.1",
+        port=api_port,
+        log_config=None,
+        access_log=False,
+    )
+    await uvicorn.Server(config).serve()
+
+
+__all__ = ["WEBUI_DIR", "create_app", "serve"]