faden-agent 0.2.7__tar.gz

faden_agent-0.2.7/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.pyc
+dist/
+build/
+*.egg-info/
+state/
+logs/
+.env
+.agent-state/

faden_agent-0.2.7/LICENSE

@@ -0,0 +1,187 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.

faden_agent-0.2.7/NOTICE

@@ -0,0 +1,15 @@
+   Fadenstack Agent
+
+   Copyright 2026 Emagin8 UG (haftungsbeschränkt) and contributors.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

faden_agent-0.2.7/OFFICIAL.md

@@ -0,0 +1,9 @@
+# Brand and Official Releases
+
+This repository is the upstream project for “Fadenstack” node agent.
+
+- You may fork and modify the code under the Apache License 2.0.
+- Please do not present modified forks as the official “Fadenstack” project.
+- Please do not use the Fadenstack name or logo in a way that implies endorsement or an official relationship.
+
+Official releases are published only from this GitHub organization/repository.

faden_agent-0.2.7/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: faden-agent
+Version: 0.2.7
+Summary: Node execution agent for Fadenstack cluster-managed runtimes.
+Author: Emagin8 UG (haftungsbeschränkt)
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: huggingface-hub<2,>=0.32
+Requires-Dist: psutil<8.0,>=5.9
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: websockets<16,>=12
+Provides-Extra: build
+Requires-Dist: pyinstaller<7.0,>=6.0; extra == 'build'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Provides-Extra: hf
+Requires-Dist: huggingface-hub<2,>=0.32; extra == 'hf'
+Provides-Extra: llm
+Requires-Dist: jinja2<4,>=3.1; extra == 'llm'
+Requires-Dist: ray[llm,serve]==2.58.0; extra == 'llm'
+Provides-Extra: ray-host
+Requires-Dist: jinja2<4,>=3.1; extra == 'ray-host'
+Requires-Dist: ray[serve]==2.58.0; extra == 'ray-host'
+Description-Content-Type: text/markdown
+
+# faden_agent
+
+`faden_agent` is the host-side execution bridge for Fadenstack node clusters.
+
+It does not perform cluster scheduling. The backend remains authoritative for:
+
+- desired state
+- placement and routing policy
+- GPU-aware filtering and load-balancing
+
+The agent responsibilities are:
+
+- enroll with one-time token
+- maintain authenticated outbound stream
+- execute node commands (Docker runtime lifecycle)
+- report heartbeat, inventory, command timeline, and events
+
+## Quick Start
+
+1. Create token in backend admin:
+   - `POST /api/admin/system/nodes/enrollment-tokens`
+2. Set environment variables on node host:
+   - `FADEN_NODE_AGENT_BACKEND_URL`
+   - `FADEN_NODE_AGENT_ENROLLMENT_TOKEN`
+   - `FADEN_NODE_AGENT_AGENT_ID`
+   - `FADEN_NODE_AGENT_HOST`
+3. Start service:
+   - `faden-agent run` (foreground, for testing)
+   - `faden-agent start` (install as systemd service)
+
+## Commands
+
+| Command                | Description                                                                        |
+| ---------------------- | ---------------------------------------------------------------------------------- |
+| `faden-agent`        | Show the configuration and a menu of what to do                                    |
+| `faden-agent run`    | Run in foreground (test connectivity, Ctrl+C to stop)                              |
+| `faden-agent start`  | Install and start as a systemd service (picks up `FADEN_NODE_AGENT_*` env vars) |
+| `faden-agent stop`   | Stop and disable the systemd service                                               |
+| `faden-agent status` | Show systemd service status                                                        |
+
+## Environment Variables
+
+- `FADEN_NODE_AGENT_BACKEND_URL` default `http://127.0.0.1:8000`
+- `FADEN_NODE_AGENT_AGENT_ID` default `hostname`
+- `FADEN_NODE_AGENT_HOST` default: this machine's address on the route to the backend, else `hostname`
+- `FADEN_NODE_AGENT_ADVERTISE_HOST` default: this machine's address on the route to the backend, else `FADEN_NODE_AGENT_HOST`
+- `FADEN_NODE_AGENT_ADVERTISE_SCHEME` default `http` (allowed: `http`, `https`)
+- `FADEN_NODE_AGENT_ENROLLMENT_TOKEN` one-time token for initial enrollment
+- `FADEN_NODE_AGENT_STATE_PATH` default `/var/lib/faden-agent/state.json` as root, `~/.local/share/faden-agent/state.json` otherwise
+- `FADEN_NODE_AGENT_HEARTBEAT_INTERVAL_SEC` default `15`
+- `FADEN_NODE_AGENT_INVENTORY_INTERVAL_SEC` default `60`
+- `FADEN_NODE_AGENT_RECONNECT_MIN_SEC` default `2`
+- `FADEN_NODE_AGENT_RECONNECT_MAX_SEC` default `30`
+- `FADEN_NODE_AGENT_REQUEST_TIMEOUT_SEC` default `20`
+- `FADEN_NODE_AGENT_VERIFY_TLS` default `true`
+- `FADEN_NODE_AGENT_LOKI_URL` Loki push endpoint (e.g. `http://10.0.0.1:3100`). When unset, the agent asks the backend where to send logs and pushes them through the backend. Either way it collects system logs (journald on Linux, Event Log on Windows), its containers' logs and Ray Serve's logs, and pushes system logs with labels `{job="node-agent", host="<advertise host>", agent_id="...", container="node-<agent id>", level="..."}`.
+- `FADEN_NODE_AGENT_LOG_BATCH_SIZE` default `100` — max log lines per collection cycle
+- `FADEN_NODE_AGENT_LOG_FLUSH_INTERVAL_SEC` default `5` — seconds between log collection cycles
+
+## Binary Installation (no Python required)
+
+Pre-built standalone binaries are available on the
+[GitHub Releases](https://github.com/fadenstack/fadenstack/releases) page
+for Linux (x86_64 and aarch64).
+
+### Linux
+
+```bash
+curl -fLO https://github.com/fadenstack/fadenstack/releases/download/node-agent-v0.2.1/faden-agent-linux-x86_64
+sudo install -m 0755 faden-agent-linux-x86_64 /usr/local/bin/faden-agent
+```
+
+Then install the systemd service (see below) or run directly:
+
+```bash
+export FADEN_NODE_AGENT_BACKEND_URL=https://your-server
+export FADEN_NODE_AGENT_ENROLLMENT_TOKEN=tok_xxx
+
+# Test connectivity first (foreground, Ctrl+C to stop)
+faden-agent run
+
+# Once working, install as a service
+faden-agent start
+```
+
+### Via CLI
+
+```bash
+faden deploy --local-node                              # on the server's own host
+faden deploy --local-node --local-node-host user@gpu1  # on another host, over SSH
+```
+
+On the server's own host, the CLI auto-detects pre-built binaries in the workspace
+`dist/` directories and uses them instead of cloning + setting up a Python venv.
+
+## Systemd
+
+A unit file template is available at:
+
+- `deploy/systemd/faden-agent.service`

faden_agent-0.2.7/README.md

@@ -0,0 +1,100 @@
+# faden_agent
+
+`faden_agent` is the host-side execution bridge for Fadenstack node clusters.
+
+It does not perform cluster scheduling. The backend remains authoritative for:
+
+- desired state
+- placement and routing policy
+- GPU-aware filtering and load-balancing
+
+The agent responsibilities are:
+
+- enroll with one-time token
+- maintain authenticated outbound stream
+- execute node commands (Docker runtime lifecycle)
+- report heartbeat, inventory, command timeline, and events
+
+## Quick Start
+
+1. Create token in backend admin:
+   - `POST /api/admin/system/nodes/enrollment-tokens`
+2. Set environment variables on node host:
+   - `FADEN_NODE_AGENT_BACKEND_URL`
+   - `FADEN_NODE_AGENT_ENROLLMENT_TOKEN`
+   - `FADEN_NODE_AGENT_AGENT_ID`
+   - `FADEN_NODE_AGENT_HOST`
+3. Start service:
+   - `faden-agent run` (foreground, for testing)
+   - `faden-agent start` (install as systemd service)
+
+## Commands
+
+| Command                | Description                                                                        |
+| ---------------------- | ---------------------------------------------------------------------------------- |
+| `faden-agent`        | Show the configuration and a menu of what to do                                    |
+| `faden-agent run`    | Run in foreground (test connectivity, Ctrl+C to stop)                              |
+| `faden-agent start`  | Install and start as a systemd service (picks up `FADEN_NODE_AGENT_*` env vars) |
+| `faden-agent stop`   | Stop and disable the systemd service                                               |
+| `faden-agent status` | Show systemd service status                                                        |
+
+## Environment Variables
+
+- `FADEN_NODE_AGENT_BACKEND_URL` default `http://127.0.0.1:8000`
+- `FADEN_NODE_AGENT_AGENT_ID` default `hostname`
+- `FADEN_NODE_AGENT_HOST` default: this machine's address on the route to the backend, else `hostname`
+- `FADEN_NODE_AGENT_ADVERTISE_HOST` default: this machine's address on the route to the backend, else `FADEN_NODE_AGENT_HOST`
+- `FADEN_NODE_AGENT_ADVERTISE_SCHEME` default `http` (allowed: `http`, `https`)
+- `FADEN_NODE_AGENT_ENROLLMENT_TOKEN` one-time token for initial enrollment
+- `FADEN_NODE_AGENT_STATE_PATH` default `/var/lib/faden-agent/state.json` as root, `~/.local/share/faden-agent/state.json` otherwise
+- `FADEN_NODE_AGENT_HEARTBEAT_INTERVAL_SEC` default `15`
+- `FADEN_NODE_AGENT_INVENTORY_INTERVAL_SEC` default `60`
+- `FADEN_NODE_AGENT_RECONNECT_MIN_SEC` default `2`
+- `FADEN_NODE_AGENT_RECONNECT_MAX_SEC` default `30`
+- `FADEN_NODE_AGENT_REQUEST_TIMEOUT_SEC` default `20`
+- `FADEN_NODE_AGENT_VERIFY_TLS` default `true`
+- `FADEN_NODE_AGENT_LOKI_URL` Loki push endpoint (e.g. `http://10.0.0.1:3100`). When unset, the agent asks the backend where to send logs and pushes them through the backend. Either way it collects system logs (journald on Linux, Event Log on Windows), its containers' logs and Ray Serve's logs, and pushes system logs with labels `{job="node-agent", host="<advertise host>", agent_id="...", container="node-<agent id>", level="..."}`.
+- `FADEN_NODE_AGENT_LOG_BATCH_SIZE` default `100` — max log lines per collection cycle
+- `FADEN_NODE_AGENT_LOG_FLUSH_INTERVAL_SEC` default `5` — seconds between log collection cycles
+
+## Binary Installation (no Python required)
+
+Pre-built standalone binaries are available on the
+[GitHub Releases](https://github.com/fadenstack/fadenstack/releases) page
+for Linux (x86_64 and aarch64).
+
+### Linux
+
+```bash
+curl -fLO https://github.com/fadenstack/fadenstack/releases/download/node-agent-v0.2.1/faden-agent-linux-x86_64
+sudo install -m 0755 faden-agent-linux-x86_64 /usr/local/bin/faden-agent
+```
+
+Then install the systemd service (see below) or run directly:
+
+```bash
+export FADEN_NODE_AGENT_BACKEND_URL=https://your-server
+export FADEN_NODE_AGENT_ENROLLMENT_TOKEN=tok_xxx
+
+# Test connectivity first (foreground, Ctrl+C to stop)
+faden-agent run
+
+# Once working, install as a service
+faden-agent start
+```
+
+### Via CLI
+
+```bash
+faden deploy --local-node                              # on the server's own host
+faden deploy --local-node --local-node-host user@gpu1  # on another host, over SSH
+```
+
+On the server's own host, the CLI auto-detects pre-built binaries in the workspace
+`dist/` directories and uses them instead of cloning + setting up a Python venv.
+
+## Systemd
+
+A unit file template is available at:
+
+- `deploy/systemd/faden-agent.service`

faden_agent-0.2.7/build-binary.sh

@@ -0,0 +1,187 @@
+#!/bin/sh
+# Build the single-file agent for one Linux platform.
+#
+# PyInstaller does not cross-compile: a linux-aarch64 build has to happen on
+# linux-aarch64. A container gives that when the host can emulate the target,
+# and it also pins the glibc the binary links against -- built on a newer
+# distro than the node runs, the agent fails there with a GLIBC version error
+# and nothing about that says "rebuild me somewhere older".
+#
+# When the host cannot produce the target at all -- an x86_64 workstation with
+# no arm64 emulation, which is the usual case -- build it on a machine that
+# is the target. --remote copies the source there, builds, and brings the
+# binary back, leaving nothing behind.
+#
+#   sh build-binary.sh                             # this machine's arch
+#   sh build-binary.sh linux-aarch64               # explicit, needs emulation
+#   sh build-binary.sh linux-aarch64 --remote sachi@10.250.10.49
+#   sh build-binary.sh linux-aarch64 --remote sachi@10.250.10.49 \
+#        --ssh-key ~/.ssh/id_dgx_spark
+#
+# The result lands in dist/, named the way /api/install/plan expects:
+#
+#   dist/faden-agent-linux-aarch64
+#
+# That is the whole publish step. A backend running from this checkout reads
+# dist/ directly, so every node install -- online or air-gapped -- verifies
+# against the file you just built. There is no second copy to keep in step;
+# there used to be, and the one being served fell a build behind in silence.
+# A real deployment has no checkout, and points `agent_binary_dir` at
+# wherever its binaries were placed.
+set -eu
+
+PLATFORM=""
+REMOTE=""
+SSH_KEY=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --remote) REMOTE="${2:-}"; shift ;;
+    --ssh-key) SSH_KEY="${2:-}"; shift ;;
+    -h|--help) sed -n '2,30p' "$0"; exit 0 ;;
+    -*) echo "Unknown option: $1" >&2; exit 2 ;;
+    *) PLATFORM="$1" ;;
+  esac
+  shift
+done
+
+if [ -z "$PLATFORM" ]; then
+  case "$(uname -m)" in
+    x86_64|amd64) PLATFORM="linux-x86_64" ;;
+    aarch64|arm64) PLATFORM="linux-aarch64" ;;
+    *) echo "Unsupported architecture: $(uname -m)" >&2; exit 2 ;;
+  esac
+fi
+
+case "$PLATFORM" in
+  linux-x86_64) DOCKER_PLATFORM="linux/amd64" ;;
+  linux-aarch64) DOCKER_PLATFORM="linux/arm64" ;;
+  *) echo "Unknown platform: $PLATFORM" >&2; exit 2 ;;
+esac
+
+SRC=$(cd "$(dirname "$0")" && pwd)
+ARTIFACT="faden-agent-$PLATFORM"
+
+# The build itself, as one string, so the local and remote paths run exactly
+# the same thing. A difference between them would show up as a binary that
+# works in one place and not the other, which is the hardest kind to chase.
+build_script() {
+  cat <<BUILD
+set -eu
+# Git Bash rewrites anything that looks like a POSIX path in an argument, so
+# "-w /src" reached the daemon as "C:/Program Files/Git/src" and every local
+# build on Windows died before starting. MSYS_NO_PATHCONV stops that; it is
+# an unset variable everywhere else, so the remote path is unchanged.
+# The bind source has to go the other way -- the daemon wants C:/... , which
+# is what "pwd -W" gives and which fails harmlessly into plain pwd on Linux.
+SRCDIR=\$(pwd -W 2>/dev/null || pwd)
+MSYS_NO_PATHCONV=1 docker run --rm --platform "$DOCKER_PLATFORM" -v "\$SRCDIR:/src" -w /src \\
+  python:3.12-slim-bookworm sh -c '
+    set -eu
+    # PyInstaller reads the ELF it is bundling: without objdump it stops with
+    # "On Linux, objdump is required", which is a build-host problem rather
+    # than anything to do with the agent.
+    apt-get update -qq && apt-get install -y -qq binutils >/dev/null
+    pip install --quiet --no-cache-dir pyinstaller .
+    pyinstaller --clean --noconfirm node_agent.spec
+    mv dist/faden-agent "dist/$ARTIFACT"
+    # Hand the output back to whoever owns the source.
+    #
+    # The container is root and the source is a bind mount, so everything it
+    # writes -- dist/, build/, the caches -- lands root-owned on the host.
+    # On a remote build that left a directory the invoking user could not
+    # delete, and the cleanup failed with nothing but "Permission denied".
+    chown -R "\$(stat -c "%u:%g" /src)" /src
+  '
+BUILD
+}
+
+# ── local ──────────────────────────────────────────────────────────────────
+
+if [ -z "$REMOTE" ]; then
+  cd "$SRC"
+  build_script | sh
+  echo
+  echo "Built: $SRC/dist/$ARTIFACT"
+  sha256sum "$SRC/dist/$ARTIFACT" 2>/dev/null || shasum -a 256 "$SRC/dist/$ARTIFACT"
+  exit 0
+fi
+
+# ── remote ─────────────────────────────────────────────────────────────────
+
+SSH="ssh -o StrictHostKeyChecking=accept-new"
+SCP="scp -o StrictHostKeyChecking=accept-new"
+if [ -n "$SSH_KEY" ]; then
+  SSH="$SSH -i $SSH_KEY"
+  SCP="$SCP -i $SSH_KEY"
+fi
+
+echo "Building $PLATFORM on $REMOTE"
+
+# Check before copying anything: a missing docker on the far end is a clearer
+# failure here than half way through a build.
+$SSH "$REMOTE" 'command -v docker >/dev/null' || {
+  echo "ERROR: no docker on $REMOTE -- the build needs it." >&2
+  exit 1
+}
+
+REMOTE_ARCH=$($SSH "$REMOTE" 'uname -m')
+case "$PLATFORM:$REMOTE_ARCH" in
+  linux-aarch64:aarch64|linux-aarch64:arm64|linux-x86_64:x86_64|linux-x86_64:amd64) ;;
+  *)
+    # Not fatal: the far end may emulate. Say so rather than silently
+    # producing a binary for the wrong machine.
+    echo "NOTE: $REMOTE is $REMOTE_ARCH, building $PLATFORM -- relies on emulation there."
+    ;;
+esac
+
+REMOTE_DIR=$($SSH "$REMOTE" 'mktemp -d -t faden-build-XXXXXX')
+
+# Clean up, and say so when it does not work.
+#
+# This was a trap ending in "|| true", which is how 36MB of source was left
+# on a machine that had only lent us a CPU -- silently, because the one thing
+# that would have reported it was the thing being suppressed.
+cleanup_remote() {
+  $SSH "$REMOTE" "rm -rf '$REMOTE_DIR'" >/dev/null 2>&1
+  if $SSH "$REMOTE" "test -d '$REMOTE_DIR'" >/dev/null 2>&1; then
+    echo "WARNING: could not remove $REMOTE:$REMOTE_DIR -- remove it by hand." >&2
+    return 1
+  fi
+  return 0
+}
+# Only for the abnormal paths; the normal one calls it explicitly below, so a
+# successful build reports a failed cleanup instead of exiting 0 regardless.
+trap 'cleanup_remote >/dev/null 2>&1 || true' INT TERM
+
+echo "  syncing source → $REMOTE:$REMOTE_DIR"
+# tar over ssh rather than rsync: rsync is not on a Git Bash install and not
+# guaranteed on a minimal node, ssh and tar are on both by definition.
+# The excludes matter -- .venv alone is hundreds of megabytes and useless on
+# the far side, and dist/ would ship a binary for the wrong architecture.
+tar -C "$SRC" \
+  --exclude=.venv --exclude=dist --exclude=build \
+  --exclude=__pycache__ --exclude='*.pyc' --exclude=.git \
+  -czf - . | $SSH "$REMOTE" "tar -C $REMOTE_DIR -xzf -"
+
+echo "  building…"
+if ! build_script | $SSH "$REMOTE" "cd $REMOTE_DIR && sh"; then
+  echo "ERROR: the build failed on $REMOTE." >&2
+  cleanup_remote || true
+  exit 1
+fi
+
+echo "  fetching artifact"
+mkdir -p "$SRC/dist"
+if ! $SCP "$REMOTE:$REMOTE_DIR/dist/$ARTIFACT" "$SRC/dist/$ARTIFACT"; then
+  echo "ERROR: built on $REMOTE but could not fetch $ARTIFACT." >&2
+  echo "       Left $REMOTE:$REMOTE_DIR in place so it can be copied by hand." >&2
+  exit 1
+fi
+
+echo "  cleaning up $REMOTE"
+cleanup_remote || true
+
+echo
+echo "Built on $REMOTE, fetched to: $SRC/dist/$ARTIFACT"
+sha256sum "$SRC/dist/$ARTIFACT" 2>/dev/null || shasum -a 256 "$SRC/dist/$ARTIFACT"

faden_agent-0.2.7/deploy/systemd/faden-agent.service

@@ -0,0 +1,32 @@
+[Unit]
+Description=fadenstack node agent
+After=network-online.target docker.service
+Wants=network-online.target
+# A start that can never succeed must stop retrying and say so.
+# The agent handles a backend outage itself (it reconnects with backoff
+# and never exits for that), so a failed *start* means something
+# structural -- most often a second agent already holding the state lock.
+# Without a limit systemd retried every 5s forever while reporting
+# "activating (auto-restart)", which reads like a slow boot rather than a
+# wedged service: observed on the DGX head at restart counter 9259, about
+# fifteen hours of looping that nothing surfaced.
+StartLimitIntervalSec=300
+StartLimitBurst=10
+
+[Service]
+Type=simple
+User=@@USER@@
+Group=@@GROUP@@
+SupplementaryGroups=docker
+EnvironmentFile=-/etc/faden-agent.env
+EnvironmentFile=-@@USER_ENV_FILE@@
+ExecStart=/usr/local/bin/faden-agent run
+Restart=always
+RestartSec=5
+TimeoutStopSec=30
+
+NoNewPrivileges=false
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target