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 run as background service. Use this mode when you want a long-lived, stable connection that can handle multiple resource types with automatic start/stop via the OS service manager. It’s ideal for:
  • Databases
  • Port-Forward Internal Services
  • Container Platforms (kubectl, aws ecs, etc)
  • Act as a Jump Host
Supported platforms
  • Linux: managed via systemd
  • macOS: managed via launchctl
  • 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 agent start
This will:
  • install or update the agent service definition
  • Enable the service to start when login
  • Start the agent immediately

​
Managing the Agent Service

You can manage the agent service using standard system commands. Here are some examples: This command will stop the agent service: 
hoop agent stop
To check the status of the agent service, use: 
hoop agent logs
To remove the agent service from your system, use: 
hoop agent remove
Notes & tips
  • Keep HOOP_KEY set in the environment where you run hoop agent start (or configure it in the service environment as directed by your setup) so the daemon can authenticate on boot.
  • If you rotate credentials, run hoop agent stop && hoop agent start to reload them.

​
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