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: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 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
API Key UsageSlack