> ## Documentation Index
> Fetch the complete documentation index at: https://hoopdev-docs-improve-idp-sso-pages.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> The agent links your private infrastructure to Hoop, acting as a proxy between your network and the central gateway.

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](/api-reference). 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`:

```yaml theme={null}
agent:
  image: hoophq/hoopdev
  environment:
    - HOOP_KEY=<your-agent-key>
```

### Kubernetes (Helm)

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

```bash theme={null}
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:

```bash theme={null}
curl -sL https://releases.hoop.dev/release/install-cli.sh | bash
```

Then run the agent as a managed background service:

```bash theme={null}
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](#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` |

## 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

<Note>
  Supported platforms

  * Linux: managed via systemd
  * macOS: managed via launchctl
</Note>

```bash theme={null}
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

```bash theme={null}
# Stop the service
hoop agent stop

# View logs
hoop agent logs

# Remove the service
hoop agent remove
```

<Note>
  * 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.
</Note>