Host Management

Prerequisites

• Role with hosts.view (read-only) and hosts.manage (write) permissions
• At least one organization configured with an org secret (see Accounts, Orgs & Locations)
• Agent binary for your target platform (Go agent >= 1.7.0 recommended, Legacy C agent supported for older Windows)

Deploying an agent

The SPOG agent runs on each managed host. It handles registration, heartbeat, host info collection, and job execution.

Step 1: Get the organization secret

1. Navigate to Settings > Organizations.
2. Copy the organization secret for the target org. This is needed for agent configuration.

Step 2: Install the agent

Linux (Go agent)

curl -O https://your-server/downloads/spog-agent-linux-amd64
chmod +x spog-agent-linux-amd64
sudo ./spog-agent-linux-amd64 --install \
  --server-url https://your-server \
  --org-secret YOUR_ORG_SECRET

Windows (Go agent)

Run the Inno Setup installer. Enter the server URL and org secret when prompted. The agent installs as a Windows service named SPOGAgent.

macOS (Go agent)

curl -O https://your-server/downloads/spog-agent-darwin-amd64
chmod +x spog-agent-darwin-amd64
sudo ./spog-agent-darwin-amd64 --install \
  --server-url https://your-server \
  --org-secret YOUR_ORG_SECRET

Windows Legacy (C agent)

Run the legacy installer for Server 2003+ / XP SP2+. Service name: SPOGLegacyAgent. Configuration file: config.ini (INI format).

Step 3: Verify registration

After installation, the agent performs the following automatically:

1. Generates a unique agent_id (stored in /var/lib/spog-agent/agent_id on Linux, %ProgramData%\SPOGAgent\agent_id on Windows).
2. Registers with the backend, sending hostname, OS info, and network interfaces.
3. Generates an Ed25519 keypair and registers the public key (Go agent only -- used for cryptographic request signing).
4. Begins the heartbeat loop (~60s interval) and host info collection (~300s interval).

The host should appear on the Hosts page within 60 seconds of installation.

Viewing and filtering hosts

Navigate to Hosts to see all hosts in your accessible organizations. Use filters to narrow the list.

Host detail tabs

Click a host to open the detail page. Information is organized into tabs.

Service and process control

Control actions create jobs that are dispatched to the agent and executed on the host. All control actions require hosts.manage permission.

Service control

1. Open the host detail page and navigate to the Services tab.
2. Find the target service in the list.
3. Click the action button: Start, Stop, Restart, Enable, or Disable.
4. A critical priority job is created and dispatched to the agent.
5. The agent executes systemctl (Linux) or sc.exe (Windows).
6. Results appear in the Jobs view. Service status updates on the next host info collection.

Process control

1. Open the host detail page and navigate to the Processes tab.
2. Find the target process in the list.
3. Click Kill.
4. A critical priority job is created. The agent sends SIGTERM/SIGKILL (Linux) or TerminateProcess (Windows).

User and group management

Manage local user accounts and groups on remote hosts. All actions create critical priority jobs.

Network diagnostics

Run network diagnostics from the host's perspective -- inside the customer network. The backend is cloud-hosted SaaS and cannot reach into customer infrastructure directly. Diagnostics create high priority jobs.

1. Open the host detail page and locate the diagnostic panel.
2. Select the diagnostic type (ping, traceroute, etc.).
3. Enter the target address or hostname.
4. Click Run. A high-priority job is dispatched to the agent.
5. View the result in the Jobs tab once the agent completes execution.

Host groups

Host groups organize hosts for policy targeting, maintenance windows, patch ring sets, and script execution. Groups are org-scoped and support parent-child hierarchy.

Creating a group

1. Navigate to Host Groups > Create Group.
2. Enter the group name and select the organization.
3. Optionally select a parent group for hierarchical organization.
4. Click Save.

Adding members

1. Open the group detail page.
2. Click Add Members and select hosts from the available list.
3. Alternatively, use bulk operations on the Hosts page to assign multiple hosts to a group at once.

Where groups are used

• Maintenance windows — schedule patching and automation within specific time windows
• Patch ring sets — define canary, early adopter, and broad deployment rings
• Policy overrides — apply specific configurations to a subset of hosts
• Script execution — target script runs to specific groups
• Service group tiers — each tier in a service group IS a host group

Service groups

Service groups enable coordinated, tier-ordered patching of dependent servers. Use them when you need to patch infrastructure in a specific order (e.g. web servers before app servers before databases).

Creating a service group

1. Navigate to Service Groups > Create Group.
2. Enter a name and description for the service group.
3. Click Save.

Adding tiers

Tiers process in order: Tier 0 patches first, then Tier 1, then Tier 2, and so on.

1. Open the service group detail page.
2. Click Add Tier.
3. Select an existing host group to assign to this tier (each tier IS a host group).
4. Configure tier settings: max concurrent hosts, success gate percentage, and optional pre/post scripts.
5. Repeat for additional tiers in dependency order.

Feature flags (kill switch)

Remotely enable or disable specific agent features for compliance and security. Requires settings.manage permission.

• Account-wide: Leave the organization field empty to disable a feature for all orgs in the account.
• Org-specific: Select a specific organization to target the flag. Org-specific flags override account-wide flags.
• Default: No flag means the feature is enabled. Delete a flag to revert to default behavior.
• Agent enforcement: Disabled features are communicated to the agent during heartbeat. The platform also blocks connections for disabled features.

Bulk operations

On the Hosts page, select multiple hosts via checkboxes to perform bulk actions.

• Run Script — execute a script on all selected hosts
• Assign Group — add selected hosts to a host group
• Assign Fingerprint Policy — set the fingerprint policy for selected hosts

Permissions

Troubleshooting