Skip to main content
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

VariableDescriptionDefault
HOOP_KEYAgent authentication DSN (required)—
LOG_LEVELLog level: debug, info, warn, errorinfo
LOG_ENCODINGLog format: json, console, human, verboseauto
HOOP_TLSCAPath to a custom TLS CA certificate—
HOOP_TLS_SKIP_VERIFYSkip TLS verification (not recommended)false

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