Configuration & Env Vars
Relevant source files
The following files were used as context for generating this wiki page:
Configuration in the Hoop project is managed through environment variables across three primary tiers: the Gateway (backend), the Agents, and the WebApp (frontend). The project utilizes these variables to define service URLs, authentication secrets, and runtime behaviors for both development and production environments.
The configuration system ensures that the Gateway can act as a central authority for authentication while allowing Agents and Client tools to connect securely using generated keys and tokens. Sources: webapp_v2/README.md, webapp_v2/CONTEXT_MIGRATION.md
WebApp V2 (React) Configuration
The modern React-based WebApp utilizes Vite for its build process. Environment variables for this tier are prefixed with VITE_ and are largely optional during development because vite.config.js provides sensible defaults.
Core Environment Variables
| Variable | Default | Purpose |
|---|---|---|
VITE_API_URL | /api | Custom backend base URL used at runtime by Axios services. |
VITE_GATEWAY_URL | http://localhost:8009 | The target for the Vite dev proxy to route /api requests. |
VITE_CLJS_URL | http://localhost:8280 | The target for the Vite dev proxy to route legacy ClojureScript assets. |
Sources: webapp_v2/README.md:65-71, webapp_v2/CONTEXT_MIGRATION.md:104-108
Development Proxy Architecture
During development, the React shell acts as a proxy to integrate the legacy ClojureScript application and the Gateway backend.
The diagram illustrates how the Vite dev server manages traffic between different project components during development. Sources: webapp_v2/README.md:21-30, webapp_v2/CONTEXT_MIGRATION.md:12-25
Gateway & Deployment Configuration
The Gateway is the central component of the Hoop architecture. Its configuration is primarily handled via a .env file generated or modified during the installation process.
Installation & Security
The installation script automatically generates a JWT_SECRET_KEY if one is not present. This key is critical for signing authentication tokens.
# Example .env generation
JWT_SECRET_KEY=$(LC_ALL=C tr -dc A-Za-z0-9_ < /dev/urandom | head -c 43 | xargs)
Sources: scripts/install.sh:111-125
Auth Configuration Flow
Authentication methods are detected automatically from the Gateway configuration. The application supports Local Auth (email/password) and OAuth/IDP (SSO).
Sources: webapp_v2/README.md:73-82
Agent Configuration
Agents require specific variables to establish a secure connection with the Gateway. The primary credential for an agent is the HOOP_KEY.
Agent Deployment Variables
| Variable | Description | Source |
|---|---|---|
HOOP_KEY | The primary authentication key for the agent to register with the Gateway. | webapp_v2/src/pages/Agents/Create/DeploymentInstructions.jsx:17 |
AWS_REGION | Used for agents requiring AWS-specific integrations (e.g., IAM RDS auth). | webapp_v2/src/pages/Agents/Create/DeploymentInstructions.jsx:77 |
Deployment Methods
Agents can be deployed via Docker, Kubernetes, or locally. In all cases, the HOOP_KEY must be provided as an environment variable to the runtime.
Secure Storage & Secret Management
The application handles "Resource Roles" which often contain sensitive credentials. These are managed via a specialized "Secrets Manager" configuration within the UI and backend.
Secret Reference Encoding
Secrets are not always stored as raw values. They can be references to external providers like AWS Secrets Manager or Vault. The system uses a specific codec for these references:
- AWS Secrets Manager: Prefixed with
_aws: - Vault KV1: Prefixed with
_vaultkv1: - Vault KV2: Prefixed with
_vaultkv2: - AWS IAM RDS: Prefixed with
_aws_iam_rds:
Sources: webapp_v2/src/pages/Roles/Configure/store.js:275-290
Connection Methods and Secret Rules
| Method | Behavior |
|---|---|
MANUAL | Wipes every reference prefix and stores raw values. |
SECRETS_MANAGER | Wipes _aws_iam_rds: references; keeps provider-specific prefixes. |
AWS_IAM | Wipes _aws: and _vaultkv*: references; keeps _aws_iam_rds:. |
Sources: webapp_v2/src/pages/Roles/Configure/store.js:335-355
Client CLI Configuration
The Hoop CLI uses configuration flags that can also be influenced by environment variables or configuration files created via hoop config create.
Key CLI Parameters
- --api-key: The token or API key for authentication.
- --api-url: The URL of the Hoop Gateway.
- --role: Filters sessions or runbooks by a specific resource role.
Sources: client/cmd/sessions.go:44-59, webapp_v2/src/pages/AiAgentsIdentities/Created/index.jsx:30-35
Summary
The Hoop configuration system is designed for flexibility across different deployment environments. It prioritizes security by utilizing JWT_SECRET_KEY for auth and specific prefixes for managed secrets. The WebApp tier remains largely zero-config for development, relying on Vite proxies to bridge the gap between backend services and legacy frontend components. Sources: webapp_v2/README.md, webapp_v2/CONTEXT_MIGRATION.md, webapp_v2/src/pages/Roles/Configure/store.js