Skip to main content

Scale the Hosted Agent with replicas

To increase how much scan traffic an agent can execute in parallel, run more than one container on the same agent token. Each container is a replica of the same agent: replicas share the agent's instruction queue and split the work between them automatically.

How replicas share work​

An agent's identity is its token and its instruction queue, not a particular container. Every replica presenting the same token polls the same queue, and each instruction is handed to exactly one replica — so scan work load-balances across replicas with no coordination, discovery, or extra configuration between them.

Each replica fetches one instruction at a time and executes that instruction's requests with up to 10 parallel workers, so N replicas give you roughly N × 10 test requests in flight. The platform does not limit how many replicas you run. Size each replica at 1 CPU and 2 GB of memory, the same as a single agent.

Add replicas​

With Docker: run the agent's install command again on another host. The script detects that an instance is already running and asks whether to continue and start a second instance. When you are adding replicas deliberately, this prompt is expected — confirm it. For automation, pass -y/--yes or set APISEC_AGENT_ASSUME_YES=true to skip the prompt.

On Kubernetes: raise spec.replicas on the agent's Deployment. See Deploy on Kubernetes for the manifest.

To remove a replica, stop that container (or lower the replica count). The remaining replicas keep polling; no rebalancing step is needed.

Operational semantics to plan around​

Replicas are invisible to the platform — it sees one agent. Three consequences follow:

  • The console shows one agent, not N replicas. Status reports carry no instance identifier, so replicas are indistinguishable to the platform and the last report wins. A replica that stops gracefully can briefly flip the agent to SHUTDOWN even while other replicas are still working; the next surviving replica's heartbeat rewrites it to ACTIVE. The reported version is likewise whatever the last-reporting replica sent. Don't treat the console status as proof of what every replica is doing — monitor individual replicas at the infrastructure level (docker ps, kubectl get pods) instead.
  • In-flight instructions are not redelivered. An instruction leaves the queue when a replica fetches it, before execution. If that replica stops mid-execution, no other replica picks the instruction up. Whether and how the platform recovers a lost instruction is handled upstream of the agent and is not covered here. Keep replicas stable while scans are running, and drain or scale down between scans when you can.
  • Token rotation cuts off every replica at once. All replicas share one token, and rotating it revokes the old token immediately — every running replica loses access until it is redeployed with the new install command. Rotate when you mean to replace or decommission the fleet; add containers, don't rotate, when you mean to scale.