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 + 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. When using local CLI execution mode, no remote protocol is needed—the agent operates directly on the machine where the CLI is installed.

​

Naming and Identification

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 (Tags): Optional supplementary identifiers for flexible filtering and grouping. Tag hosts by role (e.g., webserver, database), environment (e.g., production, staging), function (e.g., api-backend, worker-node), or region (e.g., us-east, tokyo-dc). Multiple additional names enable multi-dimensional organization and easy host discovery when assigning tasks to agents.

​

Host Management

​

Creating and Editing Hosts

Accounts UI:

1. Go to Accounts → Hosts Card (left)
2. Click + Create Host (or right-click to edit existing hosts)
3. Configure host name, public and/or private IP, connection protocol, and additional names/tags

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 Accounts under the appropriate organization based on the API key’s organization scope. Host details can be updated later through the Accounts UI. This automatic registration simplifies local deployment—just initialize an agent, and the host is tracked without manual configuration.

​

Subnet Grouping

The Accounts interface organizes hosts by subnet for better visibility and management. Hosts are automatically grouped using the first three octets of their IP addresses (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.

​

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. Test manual connection using the same credentials and protocol. Host Not Appearing in Accounts: 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.