> ## Documentation Index
> Fetch the complete documentation index at: https://hoopdev-fix-add-missing-mechanic-for-session-download-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

The agent serves as the component linking your private infrastructure to Hoop. It functions as a proxy, connecting to a central gateway and exposing services within its network scope.

You can install the agent on any Unix system. It requires an authentication key exposed as an environment variable: `HOOP_KEY`.

For deployment, the agent operates in two modes: as a standalone process (standard) or alongside any running application (embedded). Each mode has unique advantages.

## Standard Mode

The *standard mode* runs the agent as a standalone process. This run as 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)
* Act as a Jump Host

<Note>
  Supported platforms

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

*
* To create and run an agent in standard mode, use the 'hoop admin' command line by issuing the command below:

```bash theme={null}
export HOOP_KEY="$(hoop admin create agent dev)"
hoop agent start
```

This will:

* install or update the agent service definition
* Enable the service to start when login
* Start the agent immediately

#### Managing the Agent Service

You can manage the agent service using standard system commands. Here are some examples:

This command will stop the agent service:

```bash theme={null}
hoop agent stop
```

To check the status of the agent service, use:

```bash theme={null}
hoop agent logs
```

To remove the agent service from your system, use:

```bash theme={null}
hoop agent remove
```

<Note>
  Notes & tips

  * Keep HOOP\_KEY set in the environment where you run hoop agent start (or configure it in the service environment as directed by your setup) so the daemon can authenticate on boot.
  * If you rotate credentials, run hoop agent stop && hoop agent start to reload them.
</Note>

<aside>
  ⚠️ *Creating an agent through `hoop admin` doesn't generate a usable token for `hoop run`. The valid token could be obtained when creating a new connection in the webapp. Agent keys created via the command line won't work with this command.*
</aside>

## Embedded Mode

The *embedded mode* is advised for situations where the context of a runtime application is needed. The agent can run as a background process in the operating system or as a separate process close to the underlying main application. This mode is recommended if you want to:

* Execute ad-hoc tasks (rake tasks, django-admin, elixir mix tasks)
* Interactive console access
* Access REPL language environments (rails console, elixir, clojure, etc)
* Connect a single resource like a database

To create and run an agent in the embedded mode, obtain the key in the webapp when creating a connection and issue the command below:

```bash theme={null}
hoop run -- YOUR_COMMAND --YOUR_FLAGS
```

The command below demonstrates how to run the agent alongside your main application. The command that is set to run in the foreground is denoted after the `--` delimiter, while the agent operates in the background.

```bash theme={null}
hoop run --command 'rails console' -- \
  bundle exec rails s -p 3000 -b '0.0.0.0'
```

<aside>
  💡 *The streams stdout and stderr are linked to your main application, as well as the agent.*
</aside>

## Authentication Keys

To connect to a hoop gateway, the agent requires an authentication key. Each key can be revoked at any time, which allows for the disconnection of every resource associated with it.

```
<scheme>://<name>:<auth-key>@<host>:<port>?mode=<agent-mode>
```

* **scheme** - the protocol scheme to connect *http(s)* or *grpc(s)*
* **name** - the name of the authentication key
* **auth-key** - the authentication key
* **host** - the hostname or ip address of the gateway
* **port** - the port to connect to
* **mode** - the execution mode: *standard* or *embedded*

```
grpcs://dev:xagt-mzv7CRgUs23TgHpk0XNmll0TO37qfwM0D3JGQpwGPa8@use.hoop.dev:8443?mode=standard
```

> *We recommend naming these resources with the name of your environment or the context of the network, examples: `aws-prod`, `aws-us-east-1`, `production` .*

***

# Key Management

## Agent Keys

Use the hoop [command line](https://www.notion.so/Hoop-CLI-eb8e7b4536b44ba38318f2c7e68b53cc?pvs=21) to manage agent keys, these ones are only used with `hoop start agent` command.

```bash theme={null}
hoop admin create agent homolog
```

### Revoke a Key

```bash theme={null}
hoop admin delete agent homolog
```

### List Keys

```bash theme={null}
hoop admin get agents
```

```
UID            NAME      MODE       VERSION   HOSTNAME       PLATFORM      STATUS
22ab1d2f-...   default   standard   unknown   5601881aa15e   linux/arm64   ONLINE
7850eb2d-...   homolog   standard   -         -              -             -
```

<aside>
  💡 *To obtain a valid token for `hoop run`, navigate to the web application and create a connection. This will display the correct key.*
</aside>

## Organization Keys

Organization key is used to connect multiple agents with the same key. It only works with `hoop run` command and only one key is available by organization.

<aside>
  💡 *An organization key is self provisioned by default for each organization.*
</aside>

### Get the Key

```bash theme={null}
hoop admin get orgkeys
```

### Revoke the Key

```bash theme={null}
hoop admin delete orgkeys
```

<aside>
  ⚠️ *Revoking the key will disconnect all agents using this key.*
</aside>

### Create the Key

```sh theme={null}
hoop admin create orgkeys
```