Skip to main content

Agents

An agent (hagent) is a lightweight binary you run inside your own network to scan assets that aren't reachable from the public internet — internal hosts, private netblocks, and anything behind a firewall. Agent findings show up alongside externally-detected findings and can be filtered separately using the Agent source filter on the Dashboard.

Connecting a new agent​

  1. Go to Agents and click New Agent.

  2. Every agent belongs to a project — it's pre-filled with your currently selected project, or you'll be asked to pick one if you're viewing All Projects. Optionally set a Name and Tags to identify the agent — useful once you have more than one.

  3. Create the agent. HoundER generates a one-time registration token and shows it in a dialog — copy it now, it isn't shown again, and it expires after 1 hour if unused.

  4. Download the hagent binary for your platform from the agent releases page, or use the Docker image.

  5. Run it with the token, using whichever form matches your environment:

    # Linux / macOS
    HOUNDER_AGENT_TOKEN=<token> ./hagent
    # Windows PowerShell
    $env:HOUNDER_AGENT_TOKEN = "<token>"; .\hagent.exe
    # Docker
    docker run -e HOUNDER_AGENT_TOKEN=<token> registry.gitlab.com/hounder/agent:latest

The agent exchanges the token for a running identity and appears in the Agents table with status pending, moving to online once it establishes a heartbeat.

Requirements​

  • Linux (amd64/arm64), macOS (Intel or Apple Silicon), or Windows 10/11 (amd64).
  • Minimum 2 CPU / 4GB RAM.
  • Outbound network access to https://agents.hounder.io:443 — no inbound ports are required.

Managing agents​

The Agents table shows each agent's status, name/tags, version, OS, external IP, and last-seen time. From here you can rename an agent, view its logs (once online), or delete it.

Agent status values:

  • online — actively connected and available to run scans.
  • offline — was connected but hasn't sent a heartbeat recently.
  • pending — registered but hasn't connected yet (or its registration token expired before it connected — in that case, delete it and register a new one).

An agent must be online before you can select it when launching a scan.