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:

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:

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.

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.

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

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:

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.

hoop run --command 'rails console' -- \
  bundle exec rails s -p 3000 -b '0.0.0.0'

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:[e-mail]: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 to manage agent keys, these ones are only used with hoop start agent command.

hoop admin create agent homolog

Revoke a Key

hoop admin delete agent homolog

List Keys

hoop admin get agents

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

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.

Get the Key

hoop admin get orgkeys

Revoke the Key

hoop admin delete orgkeys

Create the Key

hoop admin create orgkeys