chore(deps): bump python-multipart from 0.0.20 to 0.0.31

Bumps [python-multipart](https://github.com/Kludex/python-multipart) from 0.0.20 to 0.0.31.
- [Release notes](https://github.com/Kludex/python-multipart/releases)
- [Changelog](https://github.com/Kludex/python-multipart/blob/main/CHANGELOG.md)
- [Commits](https://github.com/Kludex/python-multipart/compare/0.0.20...0.0.31)

---
updated-dependencies:
- dependency-name: python-multipart
  dependency-version: 0.0.31
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>

gateway/relay/__init__.py

@@ -113,6 +113,227 @@ def relay_inbound_config() -> tuple[Optional[str], Optional[str], int]:
     return (key or None, host or "0.0.0.0", port)
 
 
+def relay_endpoint() -> Optional[str]:
+    """The gateway's own PUBLIC inbound URL, asserted to the connector at provision.
+
+    The connector delivers signed inbound POSTs to this URL and stores it on the
+    tenant's route rows. It is gateway-asserted (the connector scopes it to the
+    verified tenant, so a dishonest gateway can only misdirect its OWN inbound).
+    The *source* of the value differs by deployment but the code path is uniform:
+    a self-hosted operator sets ``GATEWAY_RELAY_ENDPOINT`` (mirrors how they set
+    ``HERMES_DASHBOARD_PUBLIC_URL``); a hosted/NAS container has the same var
+    stamped in (NAS knows the public URL only in that case). Absent -> the
+    gateway provisions outbound-only (no inbound routes written).
+
+    Env first (Docker), then ``gateway.relay_endpoint`` in config.yaml.
+    """
+    url = os.environ.get("GATEWAY_RELAY_ENDPOINT", "").strip()
+    if not url:
+        try:
+            from gateway.run import _load_gateway_config  # late import to avoid cycle
+
+            cfg = (_load_gateway_config().get("gateway") or {})
+            url = str(cfg.get("relay_endpoint", "") or "").strip()
+        except Exception:  # noqa: BLE001 - config absence/parse must never crash boot
+            url = ""
+    return url.rstrip("/") or None
+
+
+def relay_route_keys() -> list[str]:
+    """Discriminators (guild_ids / chat_ids / paths) this gateway's tenant owns.
+
+    Gateway-provided config, paired with ``relay_endpoint()``: the connector
+    writes one route row per (routeKey -> tenant, endpoint), so route keys only
+    take effect alongside an endpoint. Empty -> outbound-only provisioning (the
+    connector accepts an empty set and writes no route rows).
+
+    ``GATEWAY_RELAY_ROUTE_KEYS`` is comma-separated; config.yaml
+    ``gateway.relay_route_keys`` may be a list or a comma string.
+    """
+    raw = os.environ.get("GATEWAY_RELAY_ROUTE_KEYS", "").strip()
+    if not raw:
+        try:
+            from gateway.run import _load_gateway_config  # late import to avoid cycle
+
+            cfg = (_load_gateway_config().get("gateway") or {})
+            val = cfg.get("relay_route_keys", "")
+            if isinstance(val, (list, tuple)):
+                return [str(k).strip() for k in val if str(k).strip()]
+            raw = str(val or "").strip()
+        except Exception:  # noqa: BLE001
+            raw = ""
+    return [k.strip() for k in raw.split(",") if k.strip()]
+
+
+def _provision_url(relay_dial_url: str) -> str:
+    """Map the ``ws(s)://…/relay`` dial URL to the ``http(s)://…/relay/provision`` POST URL."""
+    raw = relay_dial_url.rstrip("/")
+    if raw.startswith("ws://"):
+        raw = "http://" + raw[len("ws://"):]
+    elif raw.startswith("wss://"):
+        raw = "https://" + raw[len("wss://"):]
+    if raw.endswith("/relay"):
+        raw = raw[: -len("/relay")]
+    return f"{raw}/relay/provision"
+
+
+def _post_provision(
+    *,
+    provision_url: str,
+    access_token: str,
+    gateway_id: str,
+    platform: str,
+    bot_id: str,
+    gateway_endpoint: Optional[str],
+    route_keys: list[str],
+    timeout: float = 15.0,
+) -> dict:
+    """POST to the connector's ``/relay/provision`` and return the JSON body.
+
+    The connector validates ``access_token`` against NAS, derives the
+    authoritative tenant, mints the per-gateway secret + per-tenant delivery key,
+    upserts the tenant's route rows, and returns
+    ``{secret, deliveryKey, tenant, gatewayId, routeKeys}``. Raises RuntimeError
+    with a user-facing message on any non-2xx / transport failure.
+    """
+    import json
+    import urllib.error
+    import urllib.request
+
+    body: dict = {
+        "gatewayId": gateway_id,
+        "platform": platform,
+        "botId": bot_id,
+        "gatewayEndpoint": gateway_endpoint or "",
+        "routeKeys": route_keys,
+    }
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        provision_url,
+        data=data,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {access_token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            payload = json.loads(resp.read().decode())
+    except urllib.error.HTTPError as exc:
+        detail = ""
+        try:
+            detail = (json.loads(exc.read().decode()) or {}).get("error", "")
+        except Exception:
+            pass
+        raise RuntimeError(
+            f"connector returned HTTP {exc.code}" + (f": {detail}" if detail else "")
+        ) from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"could not reach connector: {exc.reason}") from exc
+
+    if not isinstance(payload, dict) or not payload.get("secret"):
+        raise RuntimeError("connector returned an unexpected response (no secret)")
+    return payload
+
+
+def self_provision_if_managed() -> bool:
+    """Managed-boot self-provision: mint relay creds in-process, no human, no disk.
+
+    Fires only on a MANAGED boot (``is_managed()``) with relay configured
+    (``relay_url()`` set) and NO per-gateway secret already present. In that case
+    the runtime resolves the agent's own Nous access token (the same
+    ``resolve_nous_access_token()`` the enroll CLI / dashboard register use),
+    POSTs ``/relay/provision`` asserting its own endpoint + route keys, and sets
+    ``GATEWAY_RELAY_ID`` / ``GATEWAY_RELAY_SECRET`` / ``GATEWAY_RELAY_DELIVERY_KEY``
+    into ``os.environ`` so the subsequent ``register_relay_adapter()`` picks them
+    up. The creds live ONLY in process memory — never written to ``~/.hermes/.env``
+    (``save_env_value`` refuses under managed anyway, and keeping the secret off
+    any volume is the stronger posture).
+
+    Stateless: process-env creds don't survive a restart, so a managed container
+    re-provisions every boot; the connector's rotation window covers a still-
+    connected prior instance. An explicitly-pinned ``GATEWAY_RELAY_SECRET`` (env
+    or config) is RESPECTED — self-provision skips so an operator pin isn't
+    stomped.
+
+    Returns True if it provisioned, False otherwise. NEVER raises: a provision
+    failure logs and returns False so the gateway still boots (and
+    ``register_relay_adapter`` will simply dial unauthenticated / be rejected,
+    rather than the whole gateway crashing).
+    """
+    import logging
+
+    logger = logging.getLogger("gateway.relay")
+
+    try:
+        from hermes_cli.config import is_managed
+    except Exception:  # noqa: BLE001
+        return False
+
+    if not is_managed():
+        return False
+    dial_url = relay_url()
+    if not dial_url:
+        return False
+
+    # Respect an already-present (pinned/stamped) secret — don't stomp it.
+    existing_id, existing_secret = relay_connection_auth()
+    if existing_id and existing_secret:
+        logger.info("relay self-provision skipped: GATEWAY_RELAY_SECRET already set")
+        return False
+
+    try:
+        from hermes_cli.auth import resolve_nous_access_token
+
+        access_token = resolve_nous_access_token()
+    except Exception as exc:  # noqa: BLE001 - boot must survive a token failure
+        logger.warning("relay self-provision skipped: could not resolve Nous token (%s)", exc)
+        return False
+
+    platform, bot_id = relay_platform_identity()
+    # gatewayId default mirrors the enroll CLI's hostname-based slug.
+    import socket
+
+    try:
+        host = socket.gethostname().strip()
+    except Exception:  # noqa: BLE001
+        host = ""
+    gateway_id = os.environ.get("GATEWAY_RELAY_ID", "").strip() or f"gw-{host or 'hermes'}"
+    endpoint = relay_endpoint()
+    route_keys = relay_route_keys()
+
+    try:
+        result = _post_provision(
+            provision_url=_provision_url(dial_url),
+            access_token=access_token,
+            gateway_id=gateway_id,
+            platform=platform,
+            bot_id=bot_id,
+            gateway_endpoint=endpoint,
+            route_keys=route_keys,
+        )
+    except RuntimeError as exc:
+        logger.warning("relay self-provision failed (%s); gateway will boot without relay auth", exc)
+        return False
+
+    # Set creds in-process so register_relay_adapter() + relay_inbound_config()
+    # read them from os.environ. Never logged.
+    os.environ["GATEWAY_RELAY_ID"] = str(result.get("gatewayId") or gateway_id)
+    os.environ["GATEWAY_RELAY_SECRET"] = str(result.get("secret") or "")
+    os.environ["GATEWAY_RELAY_DELIVERY_KEY"] = str(result.get("deliveryKey") or "")
+    tenant = str(result.get("tenant") or "")
+    logger.info(
+        "relay self-provisioned (gateway_id=%s tenant=%s routes=%d inbound=%s)",
+        os.environ["GATEWAY_RELAY_ID"],
+        tenant or "?",
+        len(route_keys),
+        "yes" if endpoint else "outbound-only",
+    )
+    return True
+
+
 def register_relay_adapter(force: bool = False, url: Optional[str] = None) -> bool:
     """Register the generic ``relay`` platform via the platform registry.
 

gateway/run.py

@@ -5116,7 +5116,17 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         # adapter dials the connector over a WebSocket, negotiates its capability
         # descriptor at handshake, and bridges inbound/outbound like any platform.
         try:
-            from gateway.relay import register_relay_adapter, relay_url
+            from gateway.relay import (
+                register_relay_adapter,
+                relay_url,
+                self_provision_if_managed,
+            )
+
+            # Managed boot: self-provision relay creds in-process (resolve the
+            # agent's NAS token -> POST /relay/provision -> set GATEWAY_RELAY_* in
+            # os.environ) BEFORE registration reads them. No-op when not managed,
+            # relay unconfigured, or a secret is already pinned. Never raises.
+            self_provision_if_managed()
 
             if register_relay_adapter():
                 logger.info("relay adapter registered (connector at %s)", relay_url())

hermes_cli/backup.py

@@ -64,6 +64,39 @@ _EXCLUDED_NAMES = {
     "cron.pid",
 }
 
+# File names that ``hermes import`` must never overwrite, matched by basename so
+# they're caught for the root profile (``gateway_state.json``) and for named
+# profiles alike (``profiles/<name>/gateway_state.json``).
+#
+# These hold *volatile gateway/process runtime state that is namespaced to the
+# machine or container the backup was taken on* — PIDs in a dead process
+# namespace, a runtime lock, the process registry, and the gateway's last
+# recorded run/desired state. Restoring them onto a different host (or a hosted
+# container) is at best meaningless and at worst actively harmful:
+#
+#   - ``gateway_state.json`` drives the container-boot reconciler
+#     (``container_boot._read_desired_state``), which only auto-starts a
+#     gateway whose recorded state is ``running``. A backup taken from a
+#     machine where the gateway was stopped (or carrying a stale/foreign
+#     value) overwrites the container's own state and leaves the gateway
+#     stuck "starting"/"cooking", disconnecting it from the Nous portal
+#     (NS-508 / the second half of NS-501).
+#   - ``gateway.pid`` / ``cron.pid`` / ``gateway.lock`` / ``processes.json``
+#     reference PIDs and locks in the *source* machine's process namespace; a
+#     numerically-equal PID in the new environment is a different process.
+#     These mirror exactly what ``container_boot._STALE_RUNTIME_FILES`` already
+#     sweeps on every container boot.
+#
+# Older backups predate the backup-side exclusions, so we filter on import too
+# rather than trusting the archive's contents.
+_IMPORT_SKIP_NAMES = {
+    "gateway_state.json",
+    "gateway.pid",
+    "cron.pid",
+    "gateway.lock",
+    "processes.json",
+}
+
 # zipfile.open() drops Unix mode bits on extract; restore tightens these to 0600.
 _SECRET_FILE_NAMES = {".env", "auth.json", "state.db"}
 
@@ -385,6 +418,7 @@ def run_import(args) -> None:
 
         errors = []
         restored = 0
+        skipped_runtime: list[str] = []
         t0 = time.monotonic()
 
         for member in members:
@@ -397,6 +431,16 @@ def run_import(args) -> None:
             if not rel:
                 continue
 
+            # Never overwrite volatile gateway/process runtime state. These are
+            # namespaced to the machine/container the backup was taken on;
+            # clobbering them (especially gateway_state.json) breaks the gateway
+            # reconciler on the target and disconnects hosted instances from the
+            # Nous portal. Matched by basename so both the root profile and
+            # named profiles (profiles/<name>/gateway_state.json) are covered.
+            if Path(rel).name in _IMPORT_SKIP_NAMES:
+                skipped_runtime.append(rel)
+                continue
+
             target = hermes_root / rel
 
             # Security: reject absolute paths and traversals
@@ -433,6 +477,16 @@ def run_import(args) -> None:
             if len(errors) > 10:
                 print(f"  ... and {len(errors) - 10} more")
 
+        if skipped_runtime:
+            print(
+                f"\n  Preserved {len(skipped_runtime)} runtime state "
+                f"file(s) (kept this machine's, not the backup's):"
+            )
+            for rel in sorted(skipped_runtime)[:10]:
+                print(f"    {rel}")
+            if len(skipped_runtime) > 10:
+                print(f"    ... and {len(skipped_runtime) - 10} more")
+
         # Post-import: restore profile wrapper scripts
         profiles_dir = hermes_root / "profiles"
         restored_profiles = []

hermes_cli/web_server.py

@@ -70,7 +70,10 @@ from gateway.status import (
 from utils import env_var_enabled
 
 try:
-    from fastapi import FastAPI, HTTPException, Request, WebSocket, WebSocketDisconnect
+    from fastapi import (
+        FastAPI, File, Form, HTTPException, Request, UploadFile,
+        WebSocket, WebSocketDisconnect,
+    )
     from fastapi.middleware.cors import CORSMiddleware
     from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, Response
     from fastapi.staticfiles import StaticFiles
@@ -82,7 +85,10 @@ except ImportError:
     try:
         from tools.lazy_deps import ensure as _lazy_ensure
         _lazy_ensure("tool.dashboard", prompt=False)
-        from fastapi import FastAPI, HTTPException, Request, WebSocket, WebSocketDisconnect
+        from fastapi import (
+            FastAPI, File, Form, HTTPException, Request, UploadFile,
+            WebSocket, WebSocketDisconnect,
+        )
         from fastapi.middleware.cors import CORSMiddleware
         from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, Response
         from fastapi.staticfiles import StaticFiles
@@ -1486,6 +1492,74 @@ async def upload_managed_file(payload: ManagedFileUpload, request: Request):
     }
 
 
+# Stream uploads to disk in fixed-size chunks. The legacy JSON endpoint above
+# buffers the whole file as a base64 data URL in a JSON body, which (a) inflates
+# the payload ~33%, (b) holds the entire file (plus its decoded copy) in memory,
+# and (c) reliably trips upstream proxy body-size/timeout limits with a 502 on
+# large backup archives (NS-501). This multipart endpoint reads the request body
+# in 1 MiB chunks straight to a temp file, enforces the size cap as it goes, and
+# atomically renames into place — constant memory, no base64 inflation.
+_UPLOAD_CHUNK_BYTES = 1024 * 1024
+
+
+@app.post("/api/files/upload-stream")
+async def upload_managed_file_stream(
+    request: Request,
+    file: UploadFile = File(...),
+    path: str = Form(...),
+    overwrite: bool = Form(True),
+):
+    policy, target, display_path = _resolve_managed_path(path, request, for_write=True)
+    if target.exists() and target.is_dir():
+        raise HTTPException(status_code=409, detail="A directory already exists at that path")
+    if target.exists() and not overwrite:
+        raise HTTPException(status_code=409, detail="File already exists")
+
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+    except PermissionError:
+        raise HTTPException(status_code=403, detail="File is not writable")
+    except OSError as exc:
+        raise HTTPException(status_code=500, detail=f"Could not create parent directory: {exc}")
+
+    # Write to a sibling temp file first so a partial/aborted upload never
+    # clobbers an existing file, then atomically rename into place.
+    tmp_fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{target.name}.", suffix=".upload", dir=str(target.parent)
+    )
+    tmp_path = Path(tmp_name)
+    total = 0
+    try:
+        with os.fdopen(tmp_fd, "wb") as out:
+            while True:
+                chunk = await file.read(_UPLOAD_CHUNK_BYTES)
+                if not chunk:
+                    break
+                total += len(chunk)
+                if total > _MANAGED_FILE_MAX_BYTES:
+                    raise HTTPException(status_code=413, detail="File is too large")
+                out.write(chunk)
+        os.replace(tmp_path, target)
+    except HTTPException:
+        tmp_path.unlink(missing_ok=True)
+        raise
+    except PermissionError:
+        tmp_path.unlink(missing_ok=True)
+        raise HTTPException(status_code=403, detail="File is not writable")
+    except OSError as exc:
+        tmp_path.unlink(missing_ok=True)
+        raise HTTPException(status_code=500, detail=f"Could not write file: {exc}")
+    finally:
+        await file.close()
+
+    return {
+        "ok": True,
+        "entry": _managed_file_entry(policy, target),
+        "path": display_path,
+        **_managed_response_meta(policy),
+    }
+
+
 @app.post("/api/files/mkdir")
 async def create_managed_directory(payload: ManagedDirectoryCreate, request: Request):
     policy, target, display_path = _resolve_managed_path(payload.path, request, for_write=True)

pyproject.toml

@@ -106,6 +106,11 @@ dependencies = [
   "pathspec==1.1.1",
   "fastapi>=0.104.0,<1",
   "uvicorn[standard]>=0.24.0,<1",
+  # Streaming multipart uploads for the dashboard file manager (NS-501).
+  # FastAPI's UploadFile/Form depend on python-multipart; it is NOT pulled in
+  # by fastapi itself, so the dashboard's multipart upload endpoint would 500
+  # without an explicit dependency here (and in the `web` extra below).
+  "python-multipart<1,>=0.0.9",
   "ptyprocess>=0.7.0,<1; sys_platform != 'win32'",
   "pywinpty>=2.0.0,<3; sys_platform == 'win32'",
   # Image resize recovery for the vision tools. Pillow shrinks oversized images
@@ -253,7 +258,7 @@ youtube = [
 # `hermes dashboard` (localhost SPA + API).  Not in core to keep the default install lean.
 # starlette==1.0.1 pinned for CVE-2026-48710 (BadHost) — fastapi pulls Starlette
 # transitively and pre-1.0.1 is the vulnerable range. See the mcp extra above.
-web = ["fastapi==0.133.1", "uvicorn[standard]==0.41.0", "starlette==1.0.1"]
+web = ["fastapi==0.133.1", "uvicorn[standard]==0.41.0", "starlette==1.0.1", "python-multipart==0.0.31"]
 all = [
   # Policy (2026-05-12): `[all]` includes only extras that genuinely
   # CAN'T be lazy-installed via `tools/lazy_deps.py` — i.e. things every

tests/gateway/relay/test_self_provision.py

@@ -0,0 +1,166 @@
+"""Unit tests for managed-boot relay self-provisioning.
+
+Covers gateway.relay.self_provision_if_managed() + the relay_endpoint() /
+relay_route_keys() config readers. The connector HTTP POST is monkeypatched
+(the cross-repo E2E exercises the real /relay/provision); these prove the
+TRIGGER logic, in-process env wiring, and fail-soft boot behaviour.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+import gateway.relay as relay
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch):
+    for k in (
+        "GATEWAY_RELAY_URL",
+        "GATEWAY_RELAY_ID",
+        "GATEWAY_RELAY_SECRET",
+        "GATEWAY_RELAY_DELIVERY_KEY",
+        "GATEWAY_RELAY_ENDPOINT",
+        "GATEWAY_RELAY_ROUTE_KEYS",
+        "GATEWAY_RELAY_PLATFORM",
+        "GATEWAY_RELAY_BOT_ID",
+    ):
+        monkeypatch.delenv(k, raising=False)
+    # Never read config.yaml off disk in these tests.
+    monkeypatch.setattr("gateway.run._load_gateway_config", lambda: {}, raising=False)
+
+
+def _stub_post(captured: dict):
+    """A fake _post_provision that records its kwargs and returns creds."""
+
+    def _fake(**kwargs):
+        captured.update(kwargs)
+        return {
+            "secret": "a" * 64,
+            "deliveryKey": "b" * 64,
+            "tenant": "org-tenant-x",
+            "gatewayId": kwargs["gateway_id"],
+            "routeKeys": kwargs["route_keys"],
+        }
+
+    return _fake
+
+
+def _arm(monkeypatch, *, managed=True, url="wss://connector.example/relay", token="nas-token"):
+    monkeypatch.setattr("hermes_cli.config.is_managed", lambda: managed)
+    monkeypatch.setattr(relay, "relay_url", lambda: url)
+    monkeypatch.setattr("hermes_cli.auth.resolve_nous_access_token", lambda: token)
+
+
+# ─────────────────────────── config readers ───────────────────────────
+
+def test_relay_endpoint_from_env(monkeypatch):
+    monkeypatch.setenv("GATEWAY_RELAY_ENDPOINT", "https://gw.example.com/inbound/")
+    assert relay.relay_endpoint() == "https://gw.example.com/inbound"
+
+
+def test_relay_endpoint_absent_is_none():
+    assert relay.relay_endpoint() is None
+
+
+def test_relay_route_keys_csv(monkeypatch):
+    monkeypatch.setenv("GATEWAY_RELAY_ROUTE_KEYS", "guild-1, guild-2 ,, guild-3")
+    assert relay.relay_route_keys() == ["guild-1", "guild-2", "guild-3"]
+
+
+def test_relay_route_keys_empty():
+    assert relay.relay_route_keys() == []
+
+
+def test_provision_url_maps_ws_to_http():
+    assert relay._provision_url("wss://c.example/relay") == "https://c.example/relay/provision"
+    assert relay._provision_url("ws://c.example/relay") == "http://c.example/relay/provision"
+    assert relay._provision_url("https://c.example") == "https://c.example/relay/provision"
+
+
+# ─────────────────────────── trigger logic ───────────────────────────
+
+def test_skips_when_not_managed(monkeypatch):
+    _arm(monkeypatch, managed=False)
+    called = {"n": 0}
+    monkeypatch.setattr(relay, "_post_provision", lambda **k: called.__setitem__("n", called["n"] + 1) or {})
+    assert relay.self_provision_if_managed() is False
+    assert called["n"] == 0
+
+
+def test_skips_when_relay_not_configured(monkeypatch):
+    _arm(monkeypatch, url=None)
+    called = {"n": 0}
+    monkeypatch.setattr(relay, "_post_provision", lambda **k: called.__setitem__("n", called["n"] + 1) or {})
+    assert relay.self_provision_if_managed() is False
+    assert called["n"] == 0
+
+
+def test_skips_when_secret_already_pinned(monkeypatch):
+    _arm(monkeypatch)
+    monkeypatch.setenv("GATEWAY_RELAY_ID", "gw-pinned")
+    monkeypatch.setenv("GATEWAY_RELAY_SECRET", "deadbeef")
+    called = {"n": 0}
+    monkeypatch.setattr(relay, "_post_provision", lambda **k: called.__setitem__("n", called["n"] + 1) or {})
+    assert relay.self_provision_if_managed() is False
+    assert called["n"] == 0
+    # The pinned secret is untouched.
+    assert relay.relay_connection_auth() == ("gw-pinned", "deadbeef")
+
+
+# ─────────────────────────── happy path ───────────────────────────
+
+def test_provisions_and_sets_env_in_process(monkeypatch):
+    _arm(monkeypatch)
+    monkeypatch.setenv("GATEWAY_RELAY_ENDPOINT", "https://gw.example.com/inbound")
+    monkeypatch.setenv("GATEWAY_RELAY_ROUTE_KEYS", "guild-1,guild-2")
+    captured: dict = {}
+    monkeypatch.setattr(relay, "_post_provision", _stub_post(captured))
+
+    assert relay.self_provision_if_managed() is True
+    # The connector POST carried the gateway-asserted endpoint + route keys.
+    assert captured["provision_url"] == "https://connector.example/relay/provision"
+    assert captured["access_token"] == "nas-token"
+    assert captured["gateway_endpoint"] == "https://gw.example.com/inbound"
+    assert captured["route_keys"] == ["guild-1", "guild-2"]
+    # Creds landed in os.environ (in-process), so register_relay_adapter() reads them.
+    gid, secret = relay.relay_connection_auth()
+    assert gid and secret == "a" * 64
+    key, _host, _port = relay.relay_inbound_config()
+    assert key == "b" * 64
+
+
+def test_outbound_only_when_no_endpoint(monkeypatch):
+    _arm(monkeypatch)
+    captured: dict = {}
+    monkeypatch.setattr(relay, "_post_provision", _stub_post(captured))
+
+    assert relay.self_provision_if_managed() is True
+    assert captured["gateway_endpoint"] is None
+    assert captured["route_keys"] == []
+    assert relay.relay_connection_auth()[1] == "a" * 64
+
+
+# ─────────────────────────── fail-soft ───────────────────────────
+
+def test_token_failure_is_non_fatal(monkeypatch):
+    _arm(monkeypatch)
+
+    def _boom():
+        raise RuntimeError("no token")
+
+    monkeypatch.setattr("hermes_cli.auth.resolve_nous_access_token", _boom)
+    # Must not raise; returns False; no creds set.
+    assert relay.self_provision_if_managed() is False
+    assert relay.relay_connection_auth() == (None, None)
+
+
+def test_connector_failure_is_non_fatal(monkeypatch):
+    _arm(monkeypatch)
+
+    def _boom(**kwargs):
+        raise RuntimeError("connector returned HTTP 503")
+
+    monkeypatch.setattr(relay, "_post_provision", _boom)
+    assert relay.self_provision_if_managed() is False
+    assert relay.relay_connection_auth() == (None, None)

tests/hermes_cli/test_backup.py

@@ -543,6 +543,126 @@ class TestImport:
         # traversal file should NOT exist outside hermes home
         assert not (tmp_path / "etc" / "passwd").exists()
 
+    def test_preserves_live_gateway_state(self, tmp_path, monkeypatch):
+        """Import must not overwrite the target's gateway_state.json.
+
+        The backup carries the *source* machine's gateway run/desired state.
+        Restoring it onto a hosted container drives the boot reconciler off
+        stale/foreign state and leaves the gateway stuck "starting",
+        disconnecting it from the Nous portal (NS-508). The live file wins.
+        """
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        # The target (e.g. hosted container) already has its own live state.
+        live_state = '{"gateway_state": "running", "desired_state": "running"}'
+        (hermes_home / "gateway_state.json").write_text(live_state)
+
+        zip_path = tmp_path / "backup.zip"
+        self._make_backup_zip(zip_path, {
+            "config.yaml": "model: test\n",
+            # A backup from a laptop where the gateway was stopped.
+            "gateway_state.json": '{"gateway_state": "stopped", "desired_state": "stopped"}',
+        })
+
+        args = Namespace(zipfile=str(zip_path), force=True)
+
+        from hermes_cli.backup import run_import
+        run_import(args)
+
+        # config.yaml is restored normally...
+        assert (hermes_home / "config.yaml").read_text() == "model: test\n"
+        # ...but the live gateway_state.json is untouched.
+        assert (hermes_home / "gateway_state.json").read_text() == live_state
+
+    def test_does_not_seed_gateway_state_when_absent(self, tmp_path, monkeypatch):
+        """A backup's gateway_state.json is dropped, not written, when the
+        target has none — a foreign state must never seed the reconciler."""
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        zip_path = tmp_path / "backup.zip"
+        self._make_backup_zip(zip_path, {
+            "config.yaml": "model: test\n",
+            "gateway_state.json": '{"gateway_state": "stopped"}',
+        })
+
+        args = Namespace(zipfile=str(zip_path), force=True)
+
+        from hermes_cli.backup import run_import
+        run_import(args)
+
+        assert (hermes_home / "config.yaml").exists()
+        assert not (hermes_home / "gateway_state.json").exists()
+
+    def test_preserves_per_profile_gateway_state(self, tmp_path, monkeypatch):
+        """The skip is matched by basename, so a named profile's
+        gateway_state.json (profiles/<name>/gateway_state.json) is preserved
+        the same way the root profile's is."""
+        hermes_home = tmp_path / ".hermes"
+        (hermes_home / "profiles" / "coder").mkdir(parents=True)
+        monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        live_state = '{"gateway_state": "running"}'
+        (hermes_home / "profiles" / "coder" / "gateway_state.json").write_text(live_state)
+
+        zip_path = tmp_path / "backup.zip"
+        self._make_backup_zip(zip_path, {
+            "config.yaml": "model: test\n",
+            "profiles/coder/config.yaml": "model: anthropic\n",
+            "profiles/coder/gateway_state.json": '{"gateway_state": "stopped"}',
+        })
+
+        args = Namespace(zipfile=str(zip_path), force=True)
+
+        from hermes_cli.backup import run_import
+        run_import(args)
+
+        # Profile config is restored, but its live gateway state is preserved.
+        assert (hermes_home / "profiles" / "coder" / "config.yaml").read_text() == "model: anthropic\n"
+        assert (
+            hermes_home / "profiles" / "coder" / "gateway_state.json"
+        ).read_text() == live_state
+
+    def test_preserves_runtime_pid_and_process_files(self, tmp_path, monkeypatch):
+        """gateway.pid / cron.pid / gateway.lock / processes.json from a backup
+        reference the source machine's process namespace and must never be
+        written over the target's."""
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+        # Live runtime files belonging to the target's own processes.
+        (hermes_home / "gateway.pid").write_text("4242")
+        (hermes_home / "processes.json").write_text('{"live": true}')
+
+        zip_path = tmp_path / "backup.zip"
+        self._make_backup_zip(zip_path, {
+            "config.yaml": "model: test\n",
+            "gateway.pid": "9999",
+            "cron.pid": "8888",
+            "gateway.lock": "7777",
+            "processes.json": '{"stale": true}',
+        })
+
+        args = Namespace(zipfile=str(zip_path), force=True)
+
+        from hermes_cli.backup import run_import
+        run_import(args)
+
+        # Live runtime files are untouched; the backup's foreign ones never land.
+        assert (hermes_home / "gateway.pid").read_text() == "4242"
+        assert (hermes_home / "processes.json").read_text() == '{"live": true}'
+        # cron.pid / gateway.lock had no live copy and were not seeded.
+        assert not (hermes_home / "cron.pid").exists()
+        assert not (hermes_home / "gateway.lock").exists()
+
     def test_confirmation_prompt_abort(self, tmp_path, monkeypatch):
         """Import aborts when user says no to confirmation."""
         hermes_home = tmp_path / ".hermes"

tests/hermes_cli/test_web_server_files.py

@@ -331,3 +331,108 @@ def test_hosted_policy_locks_to_opt_data(monkeypatch):
 
     assert str(policy.locked_root) == "/opt/data"
     assert policy.can_change_path is False
+
+
+# ---------------------------------------------------------------------------
+# Streaming multipart upload (/api/files/upload-stream) — NS-501
+# ---------------------------------------------------------------------------
+
+
+def test_stream_upload_roundtrip(forced_files_client):
+    """The multipart endpoint writes raw bytes to disk and reports the entry."""
+    client, root = forced_files_client
+    file_path = root / "out" / "backup.zip"
+    payload = b"PK\x03\x04 not really a zip but binary enough \x00\x01\x02"
+
+    created = client.post(
+        "/api/files/upload-stream",
+        data={"path": str(file_path), "overwrite": "true"},
+        files={"file": ("backup.zip", payload, "application/zip")},
+    )
+    assert created.status_code == 200, created.text
+    assert created.json()["entry"]["path"] == str(file_path)
+    assert created.json()["locked_root"] == str(root)
+    # Bytes land verbatim — no base64 round-trip, no corruption.
+    assert file_path.read_bytes() == payload
+
+
+def test_stream_upload_rejects_oversized_without_clobbering(forced_files_client, monkeypatch):
+    """Over-limit uploads return 413 and never overwrite an existing file.
+
+    The size cap is enforced while streaming (not after buffering), and the
+    temp-file + atomic-rename design means a rejected upload leaves any
+    pre-existing file at the target path untouched.
+    """
+    client, root = forced_files_client
+    file_path = root / "out" / "big.bin"
+
+    # Seed an existing file at the target path.
+    seeded = client.post(
+        "/api/files/upload-stream",
+        data={"path": str(file_path), "overwrite": "true"},
+        files={"file": ("big.bin", b"original-contents", "application/octet-stream")},
+    )
+    assert seeded.status_code == 200
+    assert file_path.read_bytes() == b"original-contents"
+
+    # Shrink the cap so a small payload trips it deterministically.
+    monkeypatch.setattr(web_server, "_MANAGED_FILE_MAX_BYTES", 8)
+    rejected = client.post(
+        "/api/files/upload-stream",
+        data={"path": str(file_path), "overwrite": "true"},
+        files={"file": ("big.bin", b"way too many bytes for the cap", "application/octet-stream")},
+    )
+    assert rejected.status_code == 413
+    # The original file must survive a rejected overwrite.
+    assert file_path.read_bytes() == b"original-contents"
+    # No stray temp files left behind in the directory.
+    leftovers = [p.name for p in file_path.parent.iterdir() if ".upload" in p.name]
+    assert leftovers == [], f"temp upload files leaked: {leftovers}"
+
+
+def test_stream_upload_respects_overwrite_false(forced_files_client):
+    client, root = forced_files_client
+    file_path = root / "keep.txt"
+
+    first = client.post(
+        "/api/files/upload-stream",
+        data={"path": str(file_path), "overwrite": "true"},
+        files={"file": ("keep.txt", b"first", "text/plain")},
+    )
+    assert first.status_code == 200
+
+    conflict = client.post(
+        "/api/files/upload-stream",
+        data={"path": str(file_path), "overwrite": "false"},
+        files={"file": ("keep.txt", b"second", "text/plain")},
+    )
+    assert conflict.status_code == 409
+    assert file_path.read_bytes() == b"first"
+
+
+def test_stream_upload_stays_under_forced_root(forced_files_client):
+    """A relative path with traversal can't escape the locked root."""
+    client, root = forced_files_client
+    escaped = client.post(
+        "/api/files/upload-stream",
+        data={"path": "../../etc/evil.txt", "overwrite": "true"},
+        files={"file": ("evil.txt", b"nope", "text/plain")},
+    )
+    assert escaped.status_code in (400, 403)
+
+
+def test_stream_upload_large_file_under_cap_succeeds(forced_files_client, monkeypatch):
+    """A multi-chunk payload (larger than the 1 MiB chunk) streams correctly."""
+    client, root = forced_files_client
+    file_path = root / "multi-chunk.bin"
+    # 2.5 MiB exercises the chunked read loop across multiple iterations.
+    payload = b"x" * (2 * 1024 * 1024 + 512 * 1024)
+
+    created = client.post(
+        "/api/files/upload-stream",
+        data={"path": str(file_path), "overwrite": "true"},
+        files={"file": ("multi-chunk.bin", payload, "application/octet-stream")},
+    )
+    assert created.status_code == 200
+    assert file_path.stat().st_size == len(payload)
+    assert file_path.read_bytes() == payload

tools/lazy_deps.py

@@ -178,6 +178,7 @@ LAZY_DEPS: dict[str, tuple[str, ...]] = {
         "fastapi==0.133.1",
         "uvicorn[standard]==0.41.0",
         "starlette==1.0.1",  # CVE-2026-48710 (BadHost) — keep lazy-install in sync with pyproject [web]
+        "python-multipart==0.0.20",  # FastAPI UploadFile/Form for streaming uploads (NS-501)
     ),
     # Vision image-resize recovery (Pillow). Pillow is now a CORE dependency
     # (pyproject `dependencies`), so this entry is a belt-and-suspenders fallback

uv.lock

@@ -1445,6 +1445,7 @@ dependencies = [
     { name = "pydantic" },
     { name = "pyjwt", extra = ["crypto"] },
     { name = "python-dotenv" },
+    { name = "python-multipart" },
     { name = "pywinpty", marker = "sys_platform == 'win32'" },
     { name = "pyyaml" },
     { name = "requests" },
@@ -1469,6 +1470,7 @@ all = [
     { name = "google-auth-httplib2" },
     { name = "google-auth-oauthlib" },
     { name = "mcp" },
+    { name = "python-multipart" },
     { name = "simple-term-menu" },
     { name = "starlette" },
     { name = "uvicorn", extra = ["standard"] },
@@ -1598,6 +1600,7 @@ termux-all = [
     { name = "google-auth-oauthlib" },
     { name = "honcho-ai" },
     { name = "mcp" },
+    { name = "python-multipart" },
     { name = "python-telegram-bot", extra = ["webhooks"] },
     { name = "simple-term-menu" },
     { name = "starlette" },
@@ -1613,6 +1616,7 @@ voice = [
 ]
 web = [
     { name = "fastapi" },
+    { name = "python-multipart" },
     { name = "starlette" },
     { name = "uvicorn", extra = ["standard"] },
 ]
@@ -1708,6 +1712,8 @@ requires-dist = [
     { name = "pytest", marker = "extra == 'dev'", specifier = "==9.0.2" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = "==1.3.0" },
     { name = "python-dotenv", specifier = "==1.2.2" },
+    { name = "python-multipart", specifier = ">=0.0.9,<1" },
+    { name = "python-multipart", marker = "extra == 'web'", specifier = "==0.0.31" },
     { name = "python-telegram-bot", extras = ["webhooks"], marker = "extra == 'messaging'", specifier = "==22.6" },
     { name = "python-telegram-bot", extras = ["webhooks"], marker = "extra == 'termux'", specifier = "==22.6" },
     { name = "pywinpty", marker = "sys_platform == 'win32'", specifier = ">=2.0.0,<3" },
@@ -3311,11 +3317,11 @@ wheels = [
 
 [[package]]
 name = "python-multipart"
-version = "0.0.27"
+version = "0.0.31"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/69/9b/f23807317a113dc36e74e75eb265a02dd1a4d9082abc3c1064acd22997c4/python_multipart-0.0.27.tar.gz", hash = "sha256:9870a6a8c5a20a5bf4f07c017bd1489006ff8836cff097b6933355ee2b49b602", size = 44043, upload-time = "2026-04-27T10:51:26.649Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/64/7e/9b35ad8f3d9ca680f7c87a88f19612fdd8da9796c4d3b46e560ac79dcc4a/python_multipart-0.0.31.tar.gz", hash = "sha256:fc631183bb13e56db3158a4909908dfb2e23565286744e798241e63750e5d680", size = 46689, upload-time = "2026-06-04T08:27:49.014Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/99/78/4126abcbdbd3c559d43e0db7f7b9173fc6befe45d39a2856cc0b8ec2a5a6/python_multipart-0.0.27-py3-none-any.whl", hash = "sha256:6fccfad17a27334bd0193681b369f476eda3409f17381a2d65aa7df3f7275645", size = 29254, upload-time = "2026-04-27T10:51:24.997Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/1e/7f7f299527a5a8ad90acd5f2f78dfa6c8495c6301a3205106ea68a84de96/python_multipart-0.0.31-py3-none-any.whl", hash = "sha256:8408153d68a9773291fc1da39a8b85a50044bddbabd2dd72e9229776b7b15e28", size = 29996, upload-time = "2026-06-04T08:27:47.804Z" },
 ]
 
 [[package]]

web/src/lib/api.ts

@@ -411,12 +411,21 @@ export const api = {
     fetchJSON<ManagedFileReadResponse>(
       `/api/files/read?path=${encodeURIComponent(path)}`,
     ),
-  uploadFile: (path: string, dataUrl: string, overwrite = true) =>
-    fetchJSON<ManagedFileWriteResponse>("/api/files/upload", {
+  uploadFile: (path: string, file: File, overwrite = true) => {
+    // Stream the raw bytes as multipart/form-data. Do NOT set Content-Type —
+    // the browser adds the multipart boundary automatically. Sending the file
+    // as base64 JSON (the old path) inflated the body ~33%, buffered the whole
+    // file in memory, and 502'd on large backup archives behind the proxy
+    // (NS-501).
+    const form = new FormData();
+    form.append("path", path);
+    form.append("overwrite", String(overwrite));
+    form.append("file", file, file.name);
+    return fetchJSON<ManagedFileWriteResponse>("/api/files/upload-stream", {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ path, data_url: dataUrl, overwrite }),
-    }),
+      body: form,
+    });
+  },
   createDirectory: (path: string) =>
     fetchJSON<ManagedFileWriteResponse>("/api/files/mkdir", {
       method: "POST",

web/src/pages/FilesPage.tsx

@@ -58,18 +58,6 @@ function formatBytes(size: number | null): string {
   return `${(size / (1024 * 1024 * 1024)).toFixed(1)} GB`;
 }
 
-function readAsDataUrl(file: globalThis.File): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const reader = new FileReader();
-    reader.addEventListener("load", () => {
-      if (typeof reader.result === "string") resolve(reader.result);
-      else reject(new Error("Could not read file"));
-    });
-    reader.addEventListener("error", () => reject(reader.error ?? new Error("Could not read file")));
-    reader.readAsDataURL(file);
-  });
-}
-
 function downloadDataUrl(dataUrl: string, name: string) {
   const link = document.createElement("a");
   link.href = dataUrl;
@@ -205,8 +193,7 @@ export default function FilesPage() {
     setUploading(true);
     try {
       for (const file of Array.from(files)) {
-        const dataUrl = await readAsDataUrl(file);
-        await api.uploadFile(joinPath(activePath, file.name), dataUrl, true);
+        await api.uploadFile(joinPath(activePath, file.name), file, true);
       }
       showToast(`${files.length} file${files.length === 1 ? "" : "s"} uploaded`, "success");
       await load();