Hosts

Hosts represent the target systems where agents execute tasks. Each host defines the network location and connection details for a machine in your infrastructure, enabling agents to operate through local CLI execution or remote connections.

​

What is a Host?

A host is a registered target system that agents can operate on. Hosts provide network addressing through IP addresses, connection methods via SSH or WinRM protocols, organizational context for grouping and management, and discovery metadata for filtering and targeting.

​

Host Configuration

​

Network Addressing

Each host requires at least one IP address: Public IP: The externally accessible IP address. Used when connecting from the agent swarm to cloud instances, accessing systems across different networks, or operating on internet-facing infrastructure. Private IP: The internal network IP address. Used when operating within the same network or VPC, accessing systems behind firewalls or NAT, or connecting through VPN or private network tunnels. At least one IP address is mandatory. Providing both creates a fallback strategy if one isn’t valid when an agent attempts to execute a task.

​

Connection Protocols

SSH (Linux/Unix): Standard protocol for Linux, Unix, and macOS systems. Requires SSH credentials (username plus password or key-based authentication), uses default port 22, and is used for most infrastructure operations. WinRM (Windows): Windows Remote Management protocol for Windows systems. Requires Windows credentials, supports both HTTP and HTTPS connections, and enables PowerShell remote execution. Windows hosts can authenticate with static Windows credentials or with a gMSA over Kerberos (see Credentials). When using local CLI execution mode, no remote protocol is needed. The agent operates directly on the machine where the CLI is installed.

​

Connection Options

The create and edit forms expose a few transport settings: Port: Each protocol has a sensible default (22 for SSH, 5985 for WinRM). Override it only when your target listens on a non-standard port, for example set 5986 (or 443/8443) when WinRM is served over HTTPS. Skip TLS verification (WinRM over HTTPS): Accepts self-signed certificates on the target. Leave this off for CA-signed targets so the certificate chain is validated. Turn it on only when you knowingly connect to a host presenting a self-signed certificate.

​

Naming and Identification

Hosts have two separate labeling concepts. Additional Names are free-form aliases. Tags are a structured, closed vocabulary that scopes which operational rules an agent receives. They are described in detail below. Host Name: The primary identifier for the host, typically matching the machine’s hostname or a descriptive name. Examples: prod-web-01, staging-db-primary, dev-workstation Additional Names: Optional free-form aliases that help you identify or match a host (for example web-01, app-server-01). They are purely for recognition and search. They do not influence which operational rules an agent receives.

​

Host Tags

Tags are a structured, closed vocabulary you assign to a host. Unlike Additional Names, they are not free text: you pick from a fixed set of axes, and each tag carries a recognizable icon. Tags scope which Operational Rules an agent receives when it works on the host. The host tag picker is organized into axes: OS and Shell are single-select. Type and Technologies accept multiple values.

​

Setting Tags

Tags are assigned from a dedicated axis-based picker in the TAGGING section of a host’s detail page. The quick create and edit dialogs do not include the tag picker, so open the host’s detail page to set or change tags.

​

How Tags Scope Operational Rules

Host tags drive operational-rule matching. A rule reaches a host only when the host’s tags satisfy every scope tag the rule carries. Adding more scope tags to a rule narrows where it applies; a rule with no scope tags applies broadly. For example, a rule scoped to postgres reaches only hosts tagged with the postgres technology. A rule scoped to both linux and database reaches only hosts that carry both tags.

​

Host Knowledge

Two parts of a host feed agents context about that machine before they start working. Knowledge: The host detail page has a read-only KNOWLEDGE section. It shows facts automatically extracted from documents you upload, resolved to this host and grouped by source document. These facts are surfaced to agents as context when they work on the host. See Knowledge for how documents are ingested and turned into facts. Description: The free-text Description field is your place for operator notes (installed tools, quirks, where credentials live, exact software versions). Its content is also surfaced to agents as context, so keep it accurate and current.

​

Host Management

​

Creating and Editing Hosts

Command Center UI:

1. Go to Command Center → Hosts (sidebar)
2. Click Create Host to open the create form (click an existing host to open its detail page and edit it)
3. Configure host name, public and/or private IP, connection protocol, port, and additional names

Set structured tags from the TAGGING section of the host’s detail page after the host exists. Hosts are always scoped to your current organization. CLI (Automatic): When creating an agent via CLI on a machine, the host is automatically registered in 2501. Network details are detected and recorded, and the host appears in Command Center under the appropriate organization based on the API key’s organization scope. Host details can be updated later through the Command Center UI. This automatic registration simplifies local deployment: just initialize an agent, and the host is tracked without manual configuration.

​

Subnet Grouping

The Command Center interface organizes hosts by subnet for better visibility and management. Hosts are automatically grouped using the first three octets of their private IP address (e.g., 192.168.1.x). This enables quick identification of hosts within the same network segment, visual topology understanding, easier management of network-scoped operations, and identification of network configuration issues.

​

Deleting Hosts

Deleting a host permanently removes the host and archives all of its agents and their tasks. A confirmation dialog in the Command Center shows how many agents will be affected before you proceed. Use this to clean up decommissioned machines without leaving orphaned agents behind.

​

Task Queuing

Tasks targeting the same host run one at a time. Additional tasks queue automatically and start when the current one finishes, preventing conflicts from concurrent changes on the same system.

​

Connection Priority

When both public and private IPs are configured, agents determine which to use based on network accessibility, execution mode (local uses localhost, swarm evaluates network routes), performance (private IPs often provide lower latency), and security (private networks may be preferred for sensitive operations). The agent automatically selects the appropriate IP address without manual intervention.

​

Integration with Agents

​

Credential Assignment

Agents must have appropriate credentials assigned to access hosts: SSH username, password, or keys for Linux/Unix hosts, WinRM credentials for Windows hosts, and host addresses for network connectivity.

​

Execution Context

When executing tasks, local mode operates on the host where CLI is installed (localhost), while remote mode uses host IP and protocol to establish connection and execute commands.

​

Troubleshooting

Connection Failures: Verify IP address accessibility from agent execution location (local machine or swarm). Check firewall rules allow SSH (port 22) or WinRM (ports 5985/5986). Validate credentials are correctly assigned to the agent. Use the Test Connection button on the agent page to diagnose issues (see Agents: Testing Connectivity). Host Not Appearing in Command Center: Verify API key organization scope matches expected organization. Check that CLI initialization completed successfully. Confirm network connectivity allowed registration. Review organization permissions. Incorrect Subnet Grouping: Verify IP address format and accuracy. Update host details if IP addresses have changed. Check for VPN or proxy interference in IP detection. Agent Can’t Reach Host: Confirm both public and private IPs if operating across networks. Verify routing between agent execution environment and target host. Test connectivity using ping or direct SSH/WinRM attempts. Review network security groups or firewall rules. For detailed credential configuration, see Credentials. For agent execution modes, see Agents.