> ## Documentation Index
> Fetch the complete documentation index at: https://hoopdev-update-to-meta-tags.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 mode is recommended when you need to connect to multiple types of resources with a single agent or desire a more stable connection for your workloads. Consider using the standard mode if you want to connect to:

* Databases
* Port-Forward Internal Services
* Container Platforms (kubectl, aws ecs, etc)
* Act as a Jump Host
*
* To create and run an agent in standard mode, use the 'hoop admin' command line by issuing the command below:

```bash
export HOOP_KEY=$(hoop admin create agent dev)
hoop start agent
```

### Connection Auto Configuration

Use the `hoop run` subcommand to automatically configure and publish a connection. It's a suitable option when you need to connect a single resource. For instance:

```bash
export HOOP_KEY=$(hoop admin get orgkeys)
hoop run --name pgdemo --postgres 'postgres://user:pwd@127.0.0.1/test'
```

### Database Connection

This example publishes a `pgdemo` connection resource.

```bash
export HOOP_KEY=$(hoop admin get orgkeys)
hoop run --name pgdemo --postgres 'postgres://<user>:<pwd>@<host>:<port>/<db>'
```

### Command Line & Applications

This example publishes a `railsc` connection resource.

```bash
export HOOP_KEY=$(hoop admin get orgkeys)
hoop run --name railsc --command 'rails console'
```

<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
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
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
hoop admin create agent homolog
```

### Revoke a Key

```bash
hoop admin delete agent homolog
```

### List Keys

```bash
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
hoop admin get orgkeys
```

### Revoke the Key

```bash
hoop admin delete orgkeys
```

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

### Create the Key

```sh
hoop admin create orgkeys
```