Connect remote agents

An agent runs remote steps on the machine where you install it. Use one when a script needs that machine’s files, tools, or services. DurpDeploy does not use SSH deployment targets.

Prepare the connection

Use an administrator account for pairing and agent management. Prepare these connections:

• During pairing: The server must reach the agent’s temporary HTTPS pairing listener.
• After pairing: The agent connects outbound to the server’s dedicated HTTPS agent endpoint, usually port 23187.

The browser URL and agent endpoint are separate. For the Compose installation, the agent endpoint is configured through DURPDEPLOY_AGENT_PUBLIC_URL in .env. Restrict listener access to the required networks.

Agents use mutual TLS, which checks both connection identities. Pairing saves the trusted server identity and connection details on the agent.

Install the agent

The agent is a separate program from the DurpDeploy server. Use the agent installation guide for binary, systemd, or container installation. Follow the installation method for your host and selected execution runtime.

Keep the agent’s state directory private and persistent. Do not copy the server database, encryption key, or server identity onto an agent. Host execution needs the selected interpreter on the agent machine. Container execution needs a supported Docker or Podman runtime and an image containing the interpreter.

Pair the agent

1. Start the agent and find its short-lived pairing code and fingerprint.
2. Open Admin → Agents in DurpDeploy.
3. Enter a display name, reachable agent address, and pairing code.
4. Compare the confirmation fingerprint with the agent’s fingerprint through a trusted channel.
5. Approve the pairing only when they match.
6. Open the agent details and confirm a recent heartbeat.

The pairing code is temporary and works once. Keep it out of tickets, chat, logs, and source control.

Route a step to the agent

1. Assign the deployment environment on the agent details page.
2. Add capability labels when you need to distinguish agent groups.
3. Edit the project’s step.
4. Set Run step on to Agent.
5. Select the execution mode and an Agent label, if needed.
6. Save the step and create a new release.

For example, assign an agent to test and give it the capability label linux. Select that label for a remote Bash step, then deploy to test.

Every matching active agent receives its own copy of the step. The deployment waits for all copies to succeed. If no agent matches, the step fails without a local fallback. Environment assignments route work and do not replace user permissions.

Choose host or container execution

Host mode runs with the agent service account’s authority. Scripts can affect resources available to that account. Use a restricted service account and trusted scripts.

Container mode requires an agent/3 agent with a ready runtime and support for the chosen interpreter. Select a container image containing bash, pwsh, or python3, as appropriate. Older agent protocols support host execution only.

Maintain the connection

Preserve paired state during restarts and upgrades. Use drain controls before planned maintenance so the agent can finish existing work. If cleanup is unconfirmed, reconcile the original workload before retrying. Do not delete agent state or re-pair to clear a cleanup warning. Read Troubleshooting for routing and connection checks.