Configuration reference
Complete reference for the Hosted Agent's environment variables, install command parameters, execution limits, and status lifecycle.
A note on naming: in configuration names, broker refers to the agent itself and manager refers to the APIsec platform. The BROKER_* variables configure the agent; MANAGER_HOST_URL and PROXY_MANAGER concern its connection to the platform.
Environment variables
The generated install command sets the variables an agent needs. Values marked "install command" are what the generated docker run sets; the default applies when the variable is absent.
| Variable | Default | Description |
|---|---|---|
MICRONAUT_ENVIRONMENTS | — (install command: broker) | Selects broker mode, the production mode: no HTTP server, outbound polling only. Required for customer deployments. |
MANAGER_HOST_URL | Internal development value (install command: https://<platform-host>/v1) | Base URL of the APIsec platform endpoint the agent calls. Always use the value from the generated install command. |
BROKER_ID | Required | The agent's ID (UUID), assigned when the agent is created. |
BROKER_TOKEN | Empty | The agent's broker token (JWT). Sent as a bearer token on every platform call. Treat it as a credential. |
BROKER_NAME | hosted-broker | Display name reported in status. |
BROKER_TYPE | hosted (install command: DOCKER_LINUX or DOCKER_WINDOWS) | Deployment type reported in status. |
BROKER_VERSION | v3.1 | Version string reported in status. Display-only — see Upgrading and versions. |
SEND_BACK_ERROR_REPORT | false (install command: true) | When true, error reports sent to the platform include stack traces. |
HEARTBEAT_SCHEDULED_INITIAL | 30s (install command: 0m) | Delay before the first instruction poll after startup. |
HEARTBEAT_SCHEDULED_FIXED | 30s (install command: 5s) | Interval between instruction-poll cycles when idle. |
HEARTBEAT_REPORT_HEALTH_FIXED | 5m | Interval for the ACTIVE health heartbeat. |
HEARTBEAT_EAGER_POLL_DURATION_MS | 10000 | After receiving work, the agent keeps fast-polling for this many milliseconds so bursts of instructions drain without waiting for the idle interval. |
HEARTBEAT_EAGER_POLL_INTERVAL_MS | 1000 | Poll interval, in milliseconds, during the fast-poll window. |
ENABLE_CERTIFICATES | false | Enables mTLS and custom-CA support for target API calls. See Certificates and mTLS. |
CERTIFICATES_BASE_PATH | /app/certificates/ | Container directory holding config.json and certificate files. |
PROXY_MANAGER | false | Routes agent-to-platform traffic through a proxy. Target API calls are never proxied. See Proxy configuration. |
PROXY_TYPE | Empty | HTTP or SOCKS. Required when PROXY_MANAGER=true. |
PROXY_HOST | Empty | Proxy hostname. Required when PROXY_MANAGER=true. |
PROXY_PORT | 0 | Proxy port. Must be greater than 0 when PROXY_MANAGER=true. |
PROXY_USERNAME | Empty | Optional proxy username. |
PROXY_PASSWORD | Empty | Optional proxy password. |
note
Despite the shared prefix, the HEARTBEAT_SCHEDULED_* and HEARTBEAT_EAGER_POLL_* variables control instruction polling. Only HEARTBEAT_REPORT_HEALTH_FIXED controls the health heartbeat that keeps an agent ACTIVE in the console.
Configuration properties without a dedicated variable
| Property | Default | Description |
|---|---|---|
execution.parallel.threads | 10 (minimum 1) | Parallel HTTP worker threads per scan batch. The agent's connection pool is sized to match. The install command does not set this property, and no dedicated environment variable is defined for it. |
Install command parameters
The generated install command runs the container as:
docker run -d --name "apisechostedagent-<agent-id>" --restart=unless-stopped --cpus=1 --memory=2g \
-v "apisec-agent-data-<agent-id>:/tmp" \
-e ... <environment variables listed above> \
<agent-image>
| Parameter | Value | Purpose |
|---|---|---|
--name | apisechostedagent-<agent-id> | Stable container name per agent. |
--restart | unless-stopped | Docker restarts the container after crashes and after platform-initiated restarts. |
--cpus / --memory | 1 / 2g | Resource caps per container. |
-v | apisec-agent-data-<agent-id>:/tmp | Named volume. Persists the restart marker so a platform-initiated restart is recognized on the next startup. |
Platform connection and retry
| Variable | Default | Purpose |
|---|---|---|
SCANSERVICE_CONNECT_TIMEOUT | 5s | Connect timeout for calls to the APIsec platform. |
SCANSERVICE_READ_TIMEOUT | 30s | Read timeout for calls to the APIsec platform. |
HEARTBEAT_POLL_RETRY_MAX_ATTEMPTS | 3 | Attempts before a failed instruction poll is given up. |
HEARTBEAT_POLL_RETRY_INITIAL_DELAY_MS | 500 | Delay before the first poll retry. |
HEARTBEAT_POLL_RETRY_MULTIPLIER | 2.0 | Backoff multiplier between poll retries. |
Request execution
Redirect handling:
- Redirects are followed only within the original host. A redirect to a different host is refused. A leading
www.is ignored when comparing hosts. - Circular redirects are refused, and the number of redirects per request is bounded.
- A scan instruction can disable redirect-following for an individual request.
Supported HTTP methods against targets: GET, POST, PUT, DELETE, OPTIONS, HEAD, TRACE, PATCH.
Agent status lifecycle
| Status | Meaning | Set when |
|---|---|---|
| PROVISIONED | Created, not yet reporting | On agent creation, and again after a token rotation. |
| ACTIVE | Agent is registered and heartbeating | Reported by the agent at container startup and on every health heartbeat (default: every 5 minutes). |
| UNRESPONSIVE | Heartbeats have gone stale | Applied by the platform to an ACTIVE agent whose last heartbeat is at least 1 hour old. Evaluated when the agent list is read, so the transition can lag. |
| SHUTDOWN | Agent stopped gracefully | Reported by the agent on graceful stop, including a platform-initiated restart. |
| DELETED | Agent removed | On deletion from the console. An ACTIVE agent cannot be deleted; deletion revokes the agent's token immediately. |
Container internals
- Base image:
apisec/java:17.0.20(Java 17). - JVM arguments baked into the image:
-Xmx2g -Xms2g -Xss512m.
note
Supported CPU architectures for the published image are not documented here. If you need a specific architecture (for example, arm64), confirm with APIsec support.