Agent guide
Connect each Docker host to its own Zero Daddy host record. An approver creates the record in the web app and shares its token through your secret store. Use the token as a Bearer credential over HTTPS. It can submit inventory, read approved plans for that host, claim work and post results. Team membership, settings, approvals and other hosts require separate credentials.
Connect a server
Create a host in the web app and save its token. Open an interactive terminal with Docker access on that server. Setup uses a POSIX shell, the Docker CLI, jq, curl and stty. Run this command on the server.
curl -fsS https://app.zero-daddy.com/setup.sh | shThe preview shows the containers and any collection errors. Use ↑ and ↓ to choose Send report, View full JSON or Cancel, then press Enter. Send report is selected first. In a basic terminal, enter 1 to send, 2 to view or 3 to cancel. Pressing Enter alone selects Send report.
After selecting Send report, paste the host token at the hidden prompt. The token stays out of the command and shell history. The helper sends the reviewed report once and prints its report ID. Open the host page to see it.
Setup reads Docker inventory without installing software, changing containers, or creating a schedule.
You can inspect /setup.sh and /collector/zd-collect.sh before running them. For CI or recurring reports, use the collector directly as described below.
Report a Docker host manually
Download the reference collector from /collector/zd-collect.sh and review it before running it on the host. It requires a POSIX shell, Docker CLI, jq and curl. Keep a reviewed copy with your operations scripts. Give its process ZD_TOKEN through your secret store. ZD_URL defaults to https://app.zero-daddy.com.
sh ./zd-collect.sh --dry-run
sh ./zd-collect.shThe dry run prints the proposed JSON. A normal run posts it to /v1/report and expects HTTP 202. The schema at /schema/report-v1.json defines the zd-report/1 contract, including collection time, completeness, parsed OS and component versions, platform, image identifiers and optional package inventory. Report each container and its evidence. Mark collection incomplete on any per-container error.
Never send environment assignments, raw environment values, Docker inspect output, credentials, or configuration file contents. Only parsed version facts belong in the version fields. A partial report cannot verify a rollout.
Schedule collection
Run the collector hourly and immediately after a change. For host cron, have your secret manager make ZD_TOKEN available to a wrapper that executes the reviewed script. An example cron entry for that wrapper follows.
0 * * * * /opt/zero-daddy/report-hostFor GitHub Actions, install the reviewed collector at the path below and give the host's self-hosted runner its own label. Add the host token to the repository or environment secrets. Select the label of the Docker host to report.
name: Report Docker inventory
on:
schedule:
- cron: '17 * * * *'
workflow_dispatch:
jobs:
report:
runs-on: [self-hosted, copix-test]
steps:
- name: Report host
env:
ZD_TOKEN: ${{ secrets.ZD_HOST_TOKEN }}
run: sh /opt/zero-daddy/zd-collect.shApply an approved plan
- Refresh inventory, then GET /v1/plans?state=approved using the host token. Read the frozen expected state, target, steps, rollback and verification conditions. Check the expiry.
- POST /v1/plans/{id}/claim. Keep the execution_id and lease_until. Claims require a report collected within 15 minutes and matching the expected state. During an active 30-minute lease a retry returns the same execution ID. A 409 means refresh inventory and re-read the plan before proceeding.
- Take your normal deployment lock. Re-check the expected digest and component versions locally, and check the expiry and lease again. Stop if anything changed.
- Apply only the approved steps. If the change fails, follow the rollback. Keep deployment and rollback changes durable in your team's configuration.
- Run zd-collect.sh immediately to post the observed host state. POST /v1/plans/{id}/result with execution_id, outcome (applied, rolled_back, or failed) and optional short notes. Omit credentials and raw logs.
A successful result records the executor's account. Resolution requires a fresh, complete report from every replica that satisfies the frozen conditions, plus the plan's applicable verification checks. Review the results on the plan page.
Verify webhook deliveries
Handle plan.approved and plan.revoked. Read the exact raw request body before parsing JSON. Read t and v1 from ZD-Signature. Reject a timestamp outside 300 seconds of your current UTC time. Compute the hex HMAC-SHA256 with the shared secret over the timestamp, a literal period, and the original body bytes. Compare signatures in constant time.
After verifying the signature, de-duplicate by ZD-Delivery-Id using a durable store and match it to the body delivery_id. Retry handling must be idempotent. Fetch and claim the approved plan through the authenticated API, re-check plan expiry and the host's expected state before applying. A revocation cancels pending work.