DurpDeploy Agent

The agent resolves startup configuration from environment variables before optional complete YAML and defaults. Custom resource limits require a policy-aware server with the same shared resource snapshot.

The DurpDeploy Agent executes deployment steps on a remote Linux host. It pairs with a DurpDeploy control plane over HTTPS, pins the server identity, decrypts authenticated deployment payloads, streams redacted logs, and runs Bash steps under the preselected unprivileged agent identity inside a hardened service or container boundary. Protocol v2 agents can also run PowerShell Core and Python steps when pwsh or python3 is installed inside that same boundary. The agent and child interpreters have zero Linux capabilities.

Build

Requires Go 1.25.7 or newer.

make build
./durpdeploy-agent version
make check

GitLab CI publishes registry.durp.info/durfy/apps/durp-deploy-agent for linux/amd64 and linux/arm64 after the tests and container contract pass. Pushes to main publish a development version, the short commit SHA, and latest as image tags. Pushes of valid semantic v* tags publish the normalized tag name and latest. Merge requests and other branches run checks without publishing application images. Tagged releases also include standalone Linux binaries.

The Kubernetes CI runner uses amd64 jobs, Docker-in-Docker, and disposable systemd test containers for local Docker sockets and rootless Podman. ARM64 images are built with QEMU emulation; ARM64 release binaries are cross-compiled. See CI setup for the runner requirements, Harbor proxies, and optional SonarCloud configuration.

The executable reports its software version, commit-count build number, source commit, and source changes. Read software versions and build numbers for release tagging, Docker build arguments, overrides, and upgrade diagnostics.

Development

Run the current agent source in the existing hardened Podman boundary:

make dev

This rebuilds the image once per invocation; it does not hot-reload source changes. The default host port 23188 maps to the agent's container pairing port 23187, while the server's direct listener uses host port 23187. If the development port is occupied, choose another one explicitly instead of falling back automatically:

AGENT_PORT=12044 make dev

The default persistent pairing state is the named Podman volume durpdeploy-agent-state. Override it only with another named volume:

AGENT_STATE_VOLUME=durpdeploy-agent-dev make dev

Stopping the disposable agent container does not remove that volume. Keep the paired state across compatible builds. Production execution must continue to use the supplied systemd or hardened container definition.

Run

Create the service account described in docs/agents.md, then start durpdeploy-agent through the provided systemd or container contract. On first start the process prints its pairing code and certificate fingerprint.

The pairing listener defaults to TCP port 23187. Set DURPDEPLOY_AGENT_LISTEN_ADDR to use an explicit address. For upgrades, follow the port migration instructions.

Configuration remains compatible with existing installations:

• DURPDEPLOY_AGENT_LISTEN_ADDR
• DURPDEPLOY_AGENT_STATE_DIR
• DURPDEPLOY_AGENT_VERSION (optional reported override; defaults to build identity)
• DURPDEPLOY_EXTRA_SCRUB_PATTERNS

The state directory contains the persistent agent identity and server pins. Do not delete it during an upgrade.

Protocol v3 adds opt-in execution in Docker or Podman step containers. Host execution remains the default. Upgrade the server for v3 first, then follow the container execution setup. Mount a runtime socket only on a dedicated execution host: socket access grants host-equivalent authority to the agent service identity.

The agent and scripts share one UID because switching to a separate runner UID would require the forbidden SETUID and SETGID capabilities. Scripts can therefore read or change agent state writable by that UID. Operators are responsible for scripts, supplied secrets, network access, and all effects inside the boundary. Use one separately hosted agent per trusted script domain.

Shared packages

DurpDeploy pins this module and uses protocol, transport, payload, and executor. Breaking wire changes require a new protocol identifier; agent-v1 changes must remain backward compatible. Upgrade the server to accept agent/2 before starting v0.2.0 agents.