Skip to main content

Deploy the Hosted Agent with Docker

To scan APIs that APIsec's cloud cannot reach, deploy the Hosted Agent as a Docker container on a host inside your network. This guide takes you from creating the agent in the console to a container reporting ACTIVE.

Prerequisites​

  • Docker installed and running on a host that can reach your target APIs.
  • Outbound TCP 443 from that host to the APIsec platform (api.apisecapps.com for production tenants; your install command embeds the correct host for your tenant). No inbound ports are required. See Networking for the full egress requirements.
  • Capacity for 1 CPU and 2 GB of memory per agent container — the install command caps the container at these values.
  • A console role that can create agents (Admin or User).
note

The install script invokes the docker binary specifically. Container runtimes that provide a docker-compatible alias may work, but the script's checks cover Docker only.

Step 1 — Create the agent in the console​

In the console, create a new Hosted Agent. For the click-path, see Manage Hosted Agents. Creating the agent generates its identity — an agent ID and a dedicated instruction queue on the platform.

Who creates the agent matters later: an agent created by an Admin is tenant-shared, so other Admins can download and manage it. An agent created by a User is private to that user — even an Admin cannot download its install command.

Step 2 — Download the install command​

Download the installation command for your host platform: Docker Linux (a bash script) or Docker Windows (a PowerShell script).

note

The install command embeds the agent's broker token — its credential to the platform. Treat the downloaded file as a secret. Re-downloading it while the current token is still valid reuses the same token identity and carries a fresh 180-day expiry, so a re-download does not disconnect a running agent. See Upgrading and versions for what that renewal does and does not cover.

Step 3 — Run the install script​

Run the downloaded script on the host. Before it starts the container, the script checks, in order:

  1. Outbound reachability. A TCP connection to the APIsec platform host on port 443. If this fails, the script exits without starting anything — fix the egress path first.
  2. Docker. The docker binary is on the PATH. On Windows, the script also runs docker info to confirm the engine is running.
  3. Existing-instance pre-flight. The script asks the platform whether an agent on this token has recently reported in. This check is best-effort; the script continues if it cannot complete.
  4. Confirmation prompt. If an instance appears to be already running, the script warns you and asks whether to continue and start a second instance. This is your guard against accidentally doubling up — but starting additional containers deliberately is how you scale with replicas. Pass -y/--yes or set APISEC_AGENT_ASSUME_YES=true to skip the prompt in automation. If you decline, the script exits without starting a container.
  5. Deploy-attempt record. The script reports your decision to the platform for audit purposes. This is best-effort and never blocks the install.

The script then runs docker run and reports success or failure.

What the docker run command configures​

The generated command looks like this (Linux shown; the Windows variant sets BROKER_TYPE=DOCKER_WINDOWS):

docker run -d --name "apisechostedagent-<agent-id>" --restart=unless-stopped --cpus=1 --memory=2g \
  -v "apisec-agent-data-<agent-id>:/tmp" \
  -e MICRONAUT_ENVIRONMENTS=broker \
  -e MANAGER_HOST_URL="https://<platform-host>/v1" \
  -e BROKER_NAME="<agent-name>" \
  -e BROKER_ID="<agent-id>" \
  -e BROKER_TYPE=DOCKER_LINUX \
  -e SEND_BACK_ERROR_REPORT=true \
  -e HEARTBEAT_SCHEDULED_INITIAL=0m \
  -e HEARTBEAT_SCHEDULED_FIXED=5s \
  -e BROKER_VERSION="<agent-version>" \
  -e BROKER_TOKEN="<broker-token>" <agent-image>

The parameters that matter operationally:

ParameterWhy it matters
--restart=unless-stoppedDocker restarts the container after a crash or a platform-initiated restart. Keep it — the platform's Restart action relies on Docker bringing the container back.
--cpus=1 --memory=2gResource caps. Size the host for 1 CPU and 2 GB per agent container.
-v apisec-agent-data-<agent-id>:/tmpA named volume that persists restart-coordination state across container restarts. It holds no credentials.
BROKER_TOKENThe agent's credential. Treat the value as a secret; it is set only in the container's environment.
HEARTBEAT_SCHEDULED_INITIAL / HEARTBEAT_SCHEDULED_FIXEDDespite the names, these set the instruction-polling cadence: first poll immediately on startup, then every 5 seconds when idle. The health heartbeat that drives the console's ACTIVE status is a separate, five-minute cycle.

For what every environment variable does, see the configuration reference.

Verify​

  1. Confirm the container is running:

    docker ps --filter name=apisechostedagent

  2. In the console, confirm the agent shows ACTIVE. The agent reports in as soon as the container starts, so the status changes from PROVISIONED to ACTIVE without a polling delay.

If the agent does not reach ACTIVE, start with Troubleshooting.