Agents

The agent connects to a central gateway and exposes services within its network scope. It can be installed on any Unix system and requires an authentication key (HOOP_KEY).

Deploying the Agent

Each deployment method below requires a HOOP_KEY. Generate one in the web app under Agents, or via the API. It looks like:

grpcs://<name>:xagt-<key>@<your-gateway>:8443?mode=standard

Supply this value as the HOOP_KEY in your chosen method below.

Docker Compose

Add the agent as a service in your docker-compose.yml:

agent:
  image: hoophq/hoopdev
  environment:
    - HOOP_KEY=<your-agent-key>

Kubernetes (Helm)

Deploy the agent into a Kubernetes cluster using the official Helm chart:

VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
helm upgrade --install hoopagent \
  https://releases.hoop.dev/release/$VERSION/hoopagent-chart-$VERSION.tgz \
  --set 'config.HOOP_KEY=<your-agent-key>'

Linux / macOS (System Service)

The hoop agent is distributed as a single binary. Install it with the official install script:

curl -sL https://releases.hoop.dev/release/install-cli.sh | bash

Then run the agent as a managed background service:

export HOOP_KEY=<your-key>
hoop agent start

This installs a system service (hoop-agent) that starts automatically on login and restarts on failure. See Standard Mode below for details.

Configuration Reference

Variable	Description	Default
`HOOP_KEY`	Agent authentication DSN (required)	—
`LOG_LEVEL`	Log level: `debug`, `info`, `warn`, `error`	`info`
`LOG_ENCODING`	Log format: `json`, `console`, `human`, `verbose`	auto
`HOOP_TLSCA`	Path to a custom TLS CA certificate	—
`HOOP_TLS_SKIP_VERIFY`	Skip TLS verification (not recommended)	`false`
`MSPRESIDIO_ANALYZER_URL`	Override the MS Presidio analyzer URL. Supports basic auth in the URL (e.g. `http://user:pass@host:5001`)	—
`MSPRESIDIO_ANONYMIZER_URL`	Override the MS Presidio anonymizer URL. Supports basic auth in the URL (e.g. `http://user:pass@host:5002`)	—
`DLP_MODE`	Override the DLP mode: `strict` (fail on errors) or `best-effort` (skip masking on errors)	—

Standard Mode

Standard mode runs the agent as a standalone background service. Use this mode when you want a long-lived, stable connection that can handle multiple resource types with automatic start/stop via the OS service manager. It’s ideal for:

Databases
Port-Forward Internal Services
Container Platforms (kubectl, aws ecs, etc)
Acting as a Jump Host

Supported platforms

Linux: managed via systemd
macOS: managed via launchctl

export HOOP_KEY=<your-key>
hoop agent start

This will:

Install or update the agent service definition
Enable the service to start on login
Start the agent immediately

Managing the Agent Service

# Stop the service
hoop agent stop

# View logs
hoop agent logs

# Remove the service
hoop agent remove

Keep HOOP_KEY set in the environment where you run hoop agent start so the daemon can authenticate on boot.
If you rotate credentials, run hoop agent stop then hoop agent start to reload them.

Introduction

Features

Clients

Quickstart

Setup & Administration

Concepts

Integrations

Deploying the Agent

Docker Compose

Kubernetes (Helm)

Linux / macOS (System Service)

Configuration Reference

Standard Mode

Managing the Agent Service

​Deploying the Agent

​Docker Compose

​Kubernetes (Helm)

​Linux / macOS (System Service)

​Configuration Reference

​Standard Mode

​Managing the Agent Service

Deploying the Agent

Docker Compose

Kubernetes (Helm)

Linux / macOS (System Service)

Configuration Reference

Standard Mode

Managing the Agent Service