deploy-agent/SPEC.md

Deploy-Agent — Build Spec

A deployment automation system: a lightweight stub agent that runs on target machines, polls a control server over HTTPS:443, downloads signed payloads, verifies signatures, and executes them. Rust everywhere.

Project root

/home/node/.openclaw/workspace/tools/deploy-agent/

Layout:

tools/deploy-agent/
├── Cargo.toml            # workspace: members = ["server", "stub", "common"]
├── common/               # shared crate: protocol types, crypto, payload format
├── server/               # control server
├── stub/                 # target-machine agent
├── payloads/             # sample payload tarballs + signing scripts
├── README.md             # architecture, threat model, build, deploy
└── justfile or Makefile  # build targets

Targets

• Linux x86_64 (primary) — musl static, rustls
• Linux aarch64 — musl static, rustls
• Windows x86_64 — Win 10/11, rustls (NOTE: modern Rust 1.94 has NO win7 targets; protocol must stay OS-agnostic so a legacy win7 build can be added later without server changes)

Stub behavior (stub/)

• Register once on first run: generate Ed25519 identity keypair, send public key + machine ID → server issues per-machine client cert (or server stores pubkey for challenge). Same ID reused on subsequent runs.
• Poll POST /poll with machine id + auth. Server returns instruction or "no-op".
• Instruction types (whitelist, NOT raw shell):
  • fetch-payload: download tarball from server, verify Ed25519 signature, extract
  • run-payload: execute the verified payload (a bundled script/binary per-platform)
  • report-status: return result + logs to server
• TLS: rustls (Linux/Windows). No OpenSSL for Linux (stays static). Windows 10/11 uses rustls too.
• Compression: flate2 with miniz_oxide backend (pure Rust, zero system deps).

Server behavior (server/)

• axum + rustls + rustls-acme (Let's Encrypt auto-provision on :443)
• mTLS client cert auth for stubs
• Per-machine instruction store (JSON file or SQLite) — which machine has which payload revision
• Endpoints:
  • POST /register — initial machine registration
  • POST /poll — authenticated stub polls for instructions
  • GET /payload/{id} — served over mTLS, stub downloads tarball
  • Admin UI or CLI to push instructions to a machine
• Signature key: server holds Ed25519 signing key; publishes public key for payload verification

Security model (must document in README)

1. mTLS machine auth (client certs issued at registration)
2. Payloads signed with Ed25519 — stub verifies before ANY execution
3. Whitelisted instruction set, NOT arbitrary remote shell
4. All traffic over TLS 1.3 (rustls)
5. Defense-in-depth: even a compromised server can't push unsigned payloads

Deliverables

1. Rust workspace that compiles
2. Stub binary for each target (Linux musl static confirmed)
3. Server binary + Let's Encrypt provisioning
4. Payload signing helper script
5. README with threat model + build/run instructions
6. .gitea/workflows/ CI to build the target matrix

Constraints

• No system lib dependencies for Linux (musl static)
• flate2/miniz_oxide for compression (pure Rust)
• rustls for TLS everywhere possible
• Ed25519 (via ed25519-dalek or ring) for signing
• Keep protocol/format identical across all OS targets
• This is security-sensitive: verify-before-execute is non-negotiable