# Puda Deployment > Use when installing, commissioning, transferring, or troubleshooting a PUDA edge driver, or when asked to export PUDA deployment logs and learnings. Applies a progressive host-to-labware SOP, records software and hardware failures, and requires evidence at every readiness gate. - Skill: `pudap/puda-deployment` (Agent Skill, multi-file: 18 files) - Install (CLI): `npx skillmds@latest add pudap/puda-deployment` - Raw SKILL.md: https://api.skillmd.com/api/skills/pudap/puda-deployment/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: pudap (https://skillmd.com/u/pudap) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/pudap/puda-deployment --- # PUDA Deployment ## Overview Use this skill to install a new PUDA-connected tool or diagnose an incomplete installation. Work from high-level infrastructure down to physical labware. Stop at the first failed gate; do not skip to motion to compensate for a software or connection failure. ## When to use - Installing PUDA, NATS, a driver repository, or an edge service. - Moving a working installation to another site or host. - Diagnosing missing/stale machine discovery, dependency/build failures, controller errors, or alignment problems. - Creating an installation log, incident record, or reusable SOP for a new tool. - Exporting deployment logs and learnings as a zip for the user. Do not use deployment as permission to move hardware. Motion, homing, gripping, or process commands require separate authorization and a clear workspace. ## Progressive gate sequence 1. **System model:** Read [references/system-and-gates.md](references/system-and-gates.md). Record site, host, tool, machine ID, controller transport, and owners. 2. **Host:** Run `scripts/preflight.sh`. Verify required commands, Docker access, clock, disk, and permissions. 3. **Network/NATS:** Read [references/network-and-nats.md](references/network-and-nats.md), run the read-only inspectors, and prove host-to-controller and client-to-broker routes separately. 4. **PUDA:** Read [references/puda-cli-project.md](references/puda-cli-project.md). Verify CLI version, login, skills, project root, and configured NATS endpoints. 5. **Source/package:** Read [references/edge-packaging.md](references/edge-packaging.md). Verify repository access, clean Git state, Python/uv workspace packaging, Docker context, and environment loading. 6. **Edge readiness:** Start/recreate only after configuration review. Require driver initialized → NATS connected → command consumers ready → acceptable queue state → fresh discovery/state. 7. **Controller:** Read [references/hardware-commissioning.md](references/hardware-commissioning.md). Use one session owner, read-only communication first, then a separately authorized low-risk command. 8. **Labware:** Read [references/labware-alignment.md](references/labware-alignment.md). Calibrate approach, intermediate, and process poses with provenance and tolerances. 9. **Operations/recovery:** Read [references/operations-recovery.md](references/operations-recovery.md). Validate live command exposure, protocol schema, stop boundaries, and incident recovery. 10. **Failure lookup:** Use [references/error-catalog.md](references/error-catalog.md) by symptom; append new proven errors after resolution. ## Mandatory evidence model Report each layer independently: | Layer | Minimum evidence | |---|---| | Host | command/version/permission checks | | Broker | listener plus successful NATS handshake/health probe | | PUDA | configured endpoint, project, login, CLI output | | Edge | logs showing driver initialization, NATS connection, subscriptions, queue state | | Controller | valid read-only response through the owning edge session | | Machine | authorized command result plus independent measurement when physical | | Labware | dated alignment record, frame, tolerance, and verifier | A heartbeat or `idle` state is not proof of controller readiness. A returned motion target is not proof of measured final pose. A digital-output acknowledgment is not proof of jaw state. ## Installation logging Copy `templates/deployment-record.md` before starting. Append actions and actual outputs as work proceeds. Use `templates/incident-record.md` when a command times out, is interrupted, or produces uncertain physical state. Redact secrets and never rewrite history to hide failed attempts. ## Export logs and learnings When asked to export the PUDA deployment logs and learnings: 1. Collect everything from the deployment session: filled deployment/incident records, site and machine profiles, labware alignment records, error-catalog updates, and any other logs or learnings produced during the work. Redact secrets. 2. Resolve the zip name from the PUDA CLI username and today's date: - Username: `puda config get user.username` - Date: `YYYY-MM-DD` (UTC) - Filename: `-.zip` (example: `zhao-2026-07-22.zip`) 3. Zip the collected files under that name and send the archive to the user. ## Completion criteria A deployment is complete only when: - Every applicable gate is checked with fresh evidence. - The expected machine appears with a fresh timestamp and live command registry. - Controller communication succeeds through the edge-owned path. - Any authorized physical commissioning result is independently verified. - Labware coordinates have provenance and tolerance records. - Environment templates contain placeholders, not credentials. - Installation and unresolved risks are recorded. ## Common pitfalls 1. `localhost` in a container points to the container unless host networking is deliberate. 2. A shallow Docker healthcheck can stay green during driver retry loops. 3. PUDA login does not grant private GitHub repository access. 4. `puda protocol validate` does not prove a command is exposed by the live edge. 5. Restarting/rebuilding can change controller session or queue behavior; inspect before retrying. 6. A second controller diagnostic session may disrupt the edge-owned session. 7. Site-specific IPs, coordinates, and active-low outputs are not portable defaults.