Agent Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Agent is a critical component of the hoop.dev ecosystem, acting as the local executor within a user's infrastructure. It facilitates secure communication between the hoop Gateway and target resources like databases, Kubernetes clusters, and servers. Agents are designed to be protocol-aware and can be deployed in various environments, including Docker, Kubernetes, or as standalone binaries on VMs.
The architecture emphasizes security by supporting multiple authentication methods, including traditional DSN keys and modern SPIFFE-based identities. Agents maintain a persistent connection to the Gateway (typically via gRPC) to receive commands and stream protocol traffic, enabling features like session recording and real-time command blocking without requiring agents on every endpoint.
Sources: README.md:144-165, webapp_v2/src/pages/Agents/Create/index.jsx:13-35
Agent Lifecycle and Management
Agents are managed through the hoop Gateway API and the web application. The lifecycle begins with the creation of an agent record, followed by deployment using a preferred method. The Gateway maintains the state of each agent, tracking its connection status (Online/Offline) and version information.
Agent Creation Flow
When a new agent is registered, the Gateway generates a unique hoopKey (token) used for authentication. Alternatively, for SPIFFE-enabled environments, a mapping is created between a SPIFFE ID and the Agent ID.
The diagram shows the logical flow from resource creation in the management interface to the successful connection of a physical agent.
Sources: webapp_v2/src/pages/Agents/Create/index.jsx:42-60, gateway/agentcontroller/controller.go:88-106, webapp_v2/src/pages/Agents/index.jsx:21-33
Management Interface
The management interface allows administrators to view, monitor, and delete agents. Key agent attributes include:
| Attribute | Description | Source |
|---|---|---|
| Name | User-defined identifier for the agent | webapp_v2/src/pages/Agents/index.jsx:75 |
| ID / UID | Unique system-generated identifier | client/cmd/admin/get.go:76 |
| Status | Current connection state (CONNECTED/DISCONNECTED) | gateway/agentcontroller/controller.go:133-143 |
| Mode | The operating mode (e.g., standard) | gateway/agentcontroller/controller.go:131 |
| Platform/Hostname | Metadata about the host environment | client/cmd/admin/get.go:76 |
| Version | The software version running on the agent | webapp_v2/src/pages/Agents/index.jsx:76 |
Deployment Methods
Hoop supports flexible deployment strategies to accommodate different infrastructure requirements.
Standard Deployment
Standard deployments use a Docker image, Helm chart, or local binary. The agent requires a HOOP_KEY to authenticate with the Gateway's gRPC endpoint.
- Docker: Setup using a Docker image from Docker Hub.
- Kubernetes: Deployment via Helm charts.
- Local/VM: Manual setup on a virtual machine or local workstation.
Sources: webapp_v2/src/pages/Agents/Create/index.jsx:13-35, scripts/local-spiffe-kubernetes.sh:35-50
SPIFFE-based Deployment
For high-security environments, agents can authenticate using SPIFFE JWT-SVIDs. This removes the need for long-lived static DSN keys.
This sequence illustrates the authentication handshake using SPIFFE identities instead of static tokens.
Sources: scripts/local-spiffe-kubernetes.sh:110-145, scripts/local-spiffe-agent.sh:95-125
Gateway-Agent Controller
The agentcontroller within the Gateway is responsible for conciliating agent deployments and ensuring their unique presence per organization. It runs periodic synchronization tasks to maintain the desired state of deployments.
Synchronization Logic
The controller performs the following tasks:
- Listing Deployments: Retrieves current active deployments via the API client.
- Organization Check: Iterates through all organizations to ensure each has a unique deployment.
- Cleanup: Automatically removes agent deployments for organizations older than 45 days.
- Conciliation: Generates new DSN keys or rotates existing ones if discrepancies are found in the deployment status.
Sources: gateway/agentcontroller/controller.go:34-75
Secret Management
The controller generates secure random keys (32 bytes) for agents. These keys are hashed before being stored in the database (models.CreateAgent or models.RotateAgentSecretKey).
Sources: gateway/agentcontroller/controller.go:148-157
Technical Specifications
Configuration Elements
Agents are configured via environment variables and CLI flags.
| Variable | Description |
|---|---|
HOOP_GRPCURL | The gRPC endpoint of the Gateway (e.g., 127.0.0.1:8010) |
HOOP_SPIFFE_MODE | Set to enforce to require SPIFFE authentication |
HOOP_SPIFFE_TRUST_DOMAIN | The expected SPIFFE trust domain |
HOOP_SPIFFE_AUDIENCE | The JWT audience enforced by the gateway |
HOOP_KEY | The DSN token for standard authentication |
Sources: scripts/local-spiffe-kubernetes.sh:150-175, scripts/local-spiffe-agent.sh:140-160
Agent Modes
- Standard Type: The default mode where the agent acts as a gateway to external resources defined in the Gateway UI.
Sources: gateway/agentcontroller/controller.go:97, scripts/local-spiffe-agent.sh:110-120
Conclusion
The Agent Architecture in hoop.dev provides a decoupled, secure, and protocol-aware execution layer. By supporting various deployment methods and advanced identity frameworks like SPIFFE, it ensures that production infrastructure remains protected while allowing granular control and auditing of all administrative sessions.