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:

shell
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:

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

It runs an agent in standalone mode and configures a connection with name pgdemo.

Database Connection

This example publishes a pgdemo connection resource.

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

additionally it's possible to use other database types: --mongodb --mssql --mysql

Command Line & Applications

This example publishes a railsc connection resource.

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

runs rails console when interacting with the connection railsc

⚠️

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.

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:

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

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

💡

The streams stdout and stderr are linked to your main application, as well as the agent.

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.

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

DSN key format

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

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

DSN key example - standard mode

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.

shell
hoop admin create agent homolog

Create a key with the name homolog in standard mode

Revoke a Key

shell
hoop admin delete agent homolog

Revoke a key with the name homolog

List Keys

shell
hoop admin get agents

List all available keys

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

💡

To obtain a valid token for hoop run, navigate to the web application and create a connection. This will display the correct key.

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.

💡

An organization key is self provisioned by default for each organization.

Get the Key

shell
hoop admin get orgkeys

Revoke the Key

shell
hoop admin delete orgkeys

⚠️

Revoking the key will disconnect all agents using this key.

Create the Key

shell
hoop admin create orgkeys

Agents