Install a Local Delegate on Linux

Last updated on Mar 24, 2026

---

Closed Beta

The new Harness Delegate is currently in closed beta and available only to select customers. Access is determined by the product team and is based on current supported use cases and steps.

This guide walks you through installing the Harness Delegate on a Linux machine. Skip to the End-to-End Demo to watch video instructions instead.

info

To learn more about the new delegate, including architecture, capabilities, and how it compares to the legacy delegate:

• New Delegate Overview — Complete guide to the new delegate
• Feature Parity — Detailed feature comparison

What's Supported

Supported Connectors

Connector	Caveats
Docker Registry	Only the DockerHub provider type
Github	All authentication types are supported
Bitbucket	All authentication types are supported
HashiCorp Vault	Only AppRole and Token Auth; set Renewal Interval to 0 (zero)
AWS Secrets Manager	Only Access Key and IAM Role Credential Type

Supported CI Steps

Step Name	Caveats
Git Clone	Github and Bitbucket
Run
Background
Run Tests
Upload to Artifactory	Requires jfrog CLI on host
Upload to GCS
Upload to S3
Upload Artifacts to Harness Artifact Registry
Save Cache to S3
Save Cache to GCS
Restore Cache from S3
Restore Cache from GCS

Quick Reference

Command	Description
./delegate server --env-file config.env	Start the delegate
nohup ./delegate server --env-file config.env > nohup-delegate.out 2>&1 &	Start in the background

Important file locations:

Item	Path
Config File	./config.env (where you created it)
Logs	./nohup-delegate.out

---

Get Harness Credentials

Before installation, obtain your Account ID, Delegate Token, and Harness URL.

Interactive Guide

Step-by-Step

1. Open Delegate settings: In the left nav, click Project Settings, then under Project-level Resources, click Delegates.

2. Create a new delegate: Click + New Delegate and choose Docker as your delegate type.

3. Copy the credentials from the docker run command:

   • ACCOUNT_ID → Your Account ID
   • DELEGATE_TOKEN → Your Delegate Token
   • MANAGER_HOST_AND_PORT → Your Harness URL

   

tip

Keep these values ready — you'll use them in the configuration file.

---

Download and Install the Delegate

Step 1: Download the Binary

For arm64:

curl -L "https://app.harness.io/public/shared/delegates/1.28.0/delegate-linux-arm64" -o delegate
chmod +x delegate

For amd64:

curl -L "https://app.harness.io/public/shared/delegates/1.28.0/delegate-linux-amd64" -o delegate
chmod +x delegate

Step 2: Create Configuration File

Create a config.env file with the credentials you obtained from the previous step:

cat > config.env <<EOF
HARNESS_ACCOUNT_ID="[Your Account ID]"
HARNESS_TOKEN="[Your Delegate Token]"
HARNESS_URL="[Your Harness URL]"
HARNESS_NAME="[Your Delegate Name]"
EOF

info

If you don't specify HARNESS_NAME, the delegate defaults to harness-delegate.

Optional: Add tags

Tags are useful for routing specific pipelines to this delegate:

cat > config.env <<EOF
HARNESS_ACCOUNT_ID="[Your Account ID]"
HARNESS_TOKEN="[Your Delegate Token]"
HARNESS_URL="[Your Harness URL]"
HARNESS_NAME="[Your Delegate Name]"
HARNESS_TAGS="production,linux"
EOF

Step 3: Start the Delegate

Run in the background:

nohup ./delegate server --env-file config.env > nohup-delegate.out 2>&1 &

Step 4: Verify Installation

Check the logs:

tail -f nohup-delegate.out

Navigate to Project Settings > Delegates in the Harness UI. You should see your delegate with a Connected status.

---

Additional Configuration

Proxy Configuration

The delegate inherits system-level proxies by default, but you can set a custom proxy through the delegate config. Edit config.env and add:

PROXY_HOST=3.139.239.136
PROXY_PORT=3128
PROXY_SCHEME=http
PROXY_USER=proxy_user
PROXY_PASSWORD=password
NO_PROXY="localhost,127.0.0.1,.corp.local,10.0.0.0/8"

Alternatively, set environment variables:

export HTTP_PROXY="http://USER:PASSWORD@PROXY_HOST:PORT"
export HTTPS_PROXY="http://USER:PASSWORD@PROXY_HOST:PORT"
export NO_PROXY="localhost,127.0.0.1,.corp.local,10.0.0.0/8"

Manual Plugin Installation

Some CI steps can run directly on the host. Harness automatically downloads required plugins, but manual installation is needed when your infrastructure lacks internet connectivity (e.g., behind a proxy or firewall).

1. Download the plugin from its source (e.g., drone-git v1.7.6).

2. Decompress: zstd -d plugin-linux-arm64.zst (or plugin-linux-amd64.zst).

3. Move to the plugins directory:

   mkdir -p ./default/plugin/drone-git/
   mv plugin-linux-* ./default/plugin/drone-git/
   chmod +x ./default/plugin/drone-git/plugin-linux-*

---

Manage the Delegate

• Stop: Find and kill the process using ps and kill commands.
• Upgrade:
  1. Download the new binary: Replace the existing delegate file.
  2. Kill the existing process.
  3. Start with the command from Step 3.

---

Configure Pipeline Delegate

For the CI stages that you want to use the new delegate with, define the stage variable HARNESS_CI_INTERNAL_ROUTE_TO_RUNNER and set it to true.

Then, set your pipeline's build infrastructure as usual. Ensure that you have set Local as the Infrastructure and that the Operating System and Architecture match the delegate you installed.

Delegate Configuration

The config.env file location:

• Default: Location where you created it
• Custom workdir: {workdir}/config.env

For configuration options that apply across all platforms — including stage capacity limits, graceful shutdown, containerless steps, init scripts, log rotation, metrics, and token management — see the Delegate Configuration Reference.

Configure Custom Working Directory

By default, the delegate stores its configuration files, logs, and cache in the current working directory.

Set the HARNESS_WORKDIR environment variable before running the binary:

export HARNESS_WORKDIR=/custom/path/to/workdir
./delegate server --env-file config.env

The delegate automatically creates the directory and subdirectories. Ensure the delegate process has read/write permissions for this directory.

Debugging

Logs

You can find the delegate logs in the following locations:

• Default: nohup-delegate.out
• Custom workdir: {workdir}/logs/delegate.log

View logs in real time:

tail -f nohup-delegate.out

Upgrading the Delegate

There is currently no automated upgrade mechanism for the new delegate. The upgrade process involves stopping the delegate, downloading the latest binary, and restarting it.

1. Stop the running delegate (kill the process).
2. Download the latest binary from the installation step, replacing the existing delegate file.
3. Start the delegate using the command from Step 3.