Skip to main content

Install Harness Delegate 2.0 (Closed Beta)

Last updated on
Closed Beta

Delegate 2.0 is currently in closed beta, and is available for select customers only. Access is determined by the product team, and is based on current supported use cases and steps.

This guide describes how to install the new Harness Delegate to local machines. Skip to the End to End Demo if you want to watch video instructions for the new delegate installation.

Important

Harness Delegate 2.0 is under Beta and can only be used for Mac Build, Android Build, and CI Stage Pipelines with limited sets of steps and connector support.

What's Supported​

Supported Connectors​

ConnectorCaveats
Docker RegistryOnly the DockerHub provider type
GithubDoes not work with Github App OAuth.
HashiCorp VaultOnly AppRole and Token Auth; set Renewal Interval to 0 (zero)
AWS Secrets ManagerOnly Access Key and IAM Role Credential Type

Supported CI Steps​

Step NameCaveats
Git CloneOnly for Github
Run

Delegate Installation Instructions​

Quick Reference​

CommandDescription
./delegate installInstall and register the service
./delegate startStart the delegate service
./delegate stopStop the service gracefully
./delegate statusShow delegate status and details
./delegate uninstallUninstall service (preserves config/logs)

Important file locations:

OSConfig FileLogsService Definition
MacOS~/.harness-delegate/config.env~/.harness-delegate/logs/~/Library/LaunchAgents/harness-delegate.plist
Linux./config.env./nohup-delegate.outN/A (runs in foreground/background)
WindowsC:\HarnessDelegate\config.envC:\HarnessDelegate\logs\Windows Service Control Manager

Get Harness Credentials​

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

  1. In the left nav, click Project Settings.

  2. Under Project-level Resources, click Delegates.

  3. Click + New Delegate.

  4. Choose Docker as your delegate type.

  5. Copy the values 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 installation command.

Download and Install the Delegate​

Download and install the correct binary for your OS.

info

The delegate runs as a user service (LaunchAgent), not a system service. It only runs when you're logged in. Enable auto-login (see step 5) to ensure it starts after system reboots.

  1. Download the delegate binary

    Replace <VERSION> with the latest version (e.g., 1.28.0):

    For arm64 (Apple Silicon):

    curl -L "https://app.harness.io/public/shared/delegates/<VERSION>/delegate-darwin-arm64" -o delegate
    chmod +x delegate

    For amd64 (Intel):

    curl -L "https://app.harness.io/public/shared/delegates/<VERSION>/delegate-darwin-amd64" -o delegate
    chmod +x delegate

    Example using version 1.28.0:

    curl -L "https://app.harness.io/public/shared/delegates/1.28.0/delegate-darwin-arm64" -o delegate

  2. Install the delegate with your credentials

    Run the install command with the credentials you obtained from the previous step:

    ./delegate install --account=[Your Account ID] \
                       --token=[Your Delegate Token] \
                       --url=[Your Harness URL] \
                       --name=[Your Delegate Name]
    info

    If you don't specify a name, the delegate will default to harness-delegate.

    Optional: Add tags for delegate selection

    Tags are optional but useful for routing specific pipelines to this delegate:

    ./delegate install --account=[Your Account ID] \
                       --token=[Your Delegate Token] \
                       --url=[Your Harness URL] \
                       --name=[Your Delegate Name] \
                       --tags="production,macos"
    View all available installation options
    ./delegate install --help

    Available options:

    • --account - Your Harness account ID (required)
    • --token - Delegate authentication token (required)
    • --url - Harness server URL (required)
    • --name - Custom delegate name (default: harness-delegate)
    • --tags - Comma-separated tags for delegate selection (optional)
    • --env-file - Path to config file (default: ~/.harness-delegate/config.env)
    • --graceful-exit-timeout - Shutdown timeout in seconds (default: 300)
    • --auto-restart-on-failure - Auto-restart on failure (default: true)

    What this command creates:

    • Workspace directory: ~/.harness-delegate
    • Configuration file: ~/.harness-delegate/config.env
    • LaunchAgent service: ~/Library/LaunchAgents/harness-delegate.plist

  3. Start the delegate service

    ./delegate start

    You should see a success message with the config location and log file path.

  4. Verify the delegate is running

    Check the status:

    ./delegate status

    View logs in real-time:

    tail -f ~/.harness-delegate/logs/delegate.log

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

  5. Enable auto-login (Recommended)

    Since the delegate runs as a user service, enable auto-login to ensure it starts after system reboots:

    1. Open System Settings (or System Preferences on older macOS)
    2. Go to Users & Groups
    3. Click the lock icon and authenticate
    4. Select Login Options
    5. Set Automatic login to your user account

Additional Configuration​

Update delegate settings:

  1. Stop the service: ./delegate stop
  2. Edit the config: nano ~/.harness-delegate/config.env
  3. Start the service: ./delegate start

Proxy configuration:

If you need proxy settings, add them to ~/.harness-delegate/config.env. See Configure Delegate Proxy Settings.

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).

To manually install a plugin:

  1. Download the plugin from its source (e.g., drone-git v1.7.6)
  2. Decompress: zstd -d plugin-darwin-arm64.zst (or plugin-darwin-amd64.zst for Intel)
  3. Move to plugins directory: 
    mkdir -p ~/.harness-delegate/default/plugin/drone-git/
    mv plugin-darwin-* ~/.harness-delegate/default/plugin/drone-git/
    chmod +x ~/.harness-delegate/default/plugin/drone-git/plugin-darwin-*

Manage the Delegate​

Stop: ./delegate stop - Gracefully shuts down (waits up to 5 minutes for tasks to complete)

Uninstall: ./delegate uninstall - Removes service registration (preserves config, logs, and binary)

Upgrade:

  1. Download new binary (replace existing delegate file)
  2. ./delegate stop
  3. ./delegate start

Navigate to Project Settings > Delegates. You should see your new delegate in the delegates list.

info

If you don't set a name for your delegate, it will default to harness-delegate

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, in order for the pipeline to select this delegate, set your pipeline's build infrastructure as normal.

Most importantly, ensure that you have set Local as the Infrastructure and that the Operating System and Architecture match the delegate you installed in the download and install delegate step.

Delegate Configuration​

The config.env file location:

  • macOS:
    • Default: ~/.harness-delegate/config.env
    • Custom workdir: {workdir}/config.env
  • Linux:
    • Default: Location where you created it
    • Custom workdir: {workdir}/config.env
  • Windows:
    • Default: C:\HarnessDelegate\config.env
    • Custom workdir: {workdir}/config.env

Set Max Stage Capacity​

With Harness Delegate 2.0, you can configure a limit for the maximum number of stages the delegate will be executing at a given time. When the delegate is handling tasks at full capacity, new tasks will be queued and picked up once the delegate's capacity is freed.

In order to configure a max limit for number of stages executed by a delegate, you should add a MAX_STAGES variable in the delegate's config.env file. The value of the MAX_STAGES should be a positive integer.

Example config.env​

If you wanted the delegate to only execute up to 5 stages a time, set MAX_STAGES=5. For example:

ACCOUNT_ID="<ACCOUNT_ID>"
TOKEN="<DELEGATE_TOKEN>"
TAGS="<your delegate tags>"
URL="<MANAGER_HOST_AND_PORT>"
NAME="<your delegate name>"
...
MAX_STAGES=5

Set Graceful Shutdown​

With Harness Delegate 2.0, you can configure a grace period to allow for a clean shutdown of running containers and processes when a pipeline execution is aborted. This ensures that any resources started by the pipeline are given time to terminate gracefully before being forcefully removed.

To configure this grace period, add the CLEANUP_GRACE_PERIOD_SECONDS variable to the delegate's config.env file. The value should be a non-negative integer representing the number of seconds to wait before forcefully terminating resources.

If the grace period is set to 0 (default), the delegate will immediately send a SIGKILL signal to stop containers and processes. If a positive value is configured, the delegate will first send a SIGTERM signal. After the grace period expires, any resources that are still running will be terminated with a SIGKILL.

Example config.env​

If you want the delegate to wait up to 30 seconds before forcefully stopping any running containers or processes, set CLEANUP_GRACE_PERIOD_SECONDS=30. For example:

ACCOUNT_ID="<ACCOUNT_ID>"
TOKEN="<DELEGATE_TOKEN>"
TAGS="<your delegate tags>"
URL="<MANAGER_HOST_AND_PORT>"
NAME="<your delegate name>"
...
CLEANUP_GRACE_PERIOD_SECONDS=30

Configure Custom Working Directory​

By default, the delegate stores its configuration files, logs, and cache in a standard location. You can customize this location using the HARNESS_WORKDIR variable.

Default locations:

  • Windows: C:\HarnessDelegate
  • Linux/macOS: ~/.harness-delegate

How to configure:

Use the --workdir flag during installation:

./delegate install --account=[Account ID] \
                   --token=[Delegate Token] \
                   --url=[Harness URL] \
                   --name=[Your Delegate Name] \
                   --workdir=/custom/path/to/workdir

Notes:

  • 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:

  • macOS:
    • Default: ~/.harness-delegate/logs/delegate.log
    • Custom workdir: {workdir}/logs/delegate.log
  • Linux:
    • Default: nohup-delegate.out
    • Custom workdir: {workdir}/logs/delegate.log
  • Windows:
    • Default: C:\HarnessDelegate\logs\delegate.log
    • Custom workdir: {workdir}/logs/delegate.log

Log File Configuration​

The delegate supports automatic log rotation and sanitization. Configure these using environment variables in your config.env:

# Enable/disable file logging
LOG_ENABLE_FILE_LOGGING=true


# Log rotation settings
LOG_MAX_SIZE_MB=100        # Rotate at 100MB
LOG_MAX_BACKUPS=3          # Keep 3 old files
LOG_MAX_AGE_DAYS=28        # Delete after 28 days
LOG_COMPRESS=false         # Compress rotated logs

View logs in real-time:

MacOS:

tail -f ~/.harness-delegate/logs/delegate.log

Linux:

tail -f nohup-delegate.out

Windows:

Get-Content -Path "C:\HarnessDelegate\logs\delegate.log" -Tail 20 -Wait

Metrics​

Delegate 2.0 exposes metrics on the /metrics endpoint for monitoring and observability. By default, the metrics endpoint is available at http://localhost:3000/metrics.

End to End Demo​

This video walks through an end to end demo of the delegate installation, including usage and a pipeline execution.