Agent is the component that connects your private infra-structure with Hoop. It act as a proxy connecting to a central gateway exposing any services in the scope of its network.

The agent can be installed in any Unix system. It requires an authentication key that is exposed as an environment variable: HOOP_DSN.

In order to deploy it, the agent can run in two modes: as a standalone process (standard) or next to any running application (embedded), each one has its own advantages.

Standard Mode

The standard mode runs the agent in a standalone process, it's recommended when you wish to connect to multiple kinds of resources in a single agent or having a more stable connection within your workloads. It's recommend if you wish 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 the standard mode, use the hoop admin command line issuing the command below:

shell
export HOOP_DSN=$(hoop admin create agent dev)
hoop start agent

Embedded Mode

The embedded mode is recommended when the context of a runtime application is needed. The agent could run in the background as another process in the operating system, or in a separated process close to the underline main application. This mode is recommended if you wish to:

Execute ad-hoc tasks (rake tasks, django-admin, elixir mix tasks)

Interactive console access

Access REPL language environments (rails console, elixir, clojure, etc)

To create and run an agent in the embedded mode, use the hoop admin command line issuing the command below:

shell
export HOOP_DSN=$(hoop admin create agent prod --mode embedded)
hoop start agent

Authentication Keys (DSN)

To connect to a hoop gateway the agent requires an authentication key. Each one of them can be revoked any time, allowing to disconnect every resource that is 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@app.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

Use the hoop command line to manage agent keys.

Standard Mode

shell
hoop admin create agent homolog

Create a key with the name homolog in standard mode

Embedded Mode

shell
hoop admin create agent prod --mode embedded

Create a key with the name prod in embedded 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   -         -              -             -

Docker Heroku Kubernetes Unix / Linux

Setup

Standard Mode

Embedded Mode

Authentication Keys (DSN)

Key Management

Standard Mode

Embedded Mode

Revoke a Key

List Keys