Host Management

Every target PC enrolled through nefia vpn invite becomes a host in your Nefia configuration. This guide covers how to list, inspect, organize, and target hosts for remote operations.

Listing Hosts

View all enrolled hosts with their connection status:

nefia hosts list

The VPN column reflects the current tunnel status. Hosts with an offline status have no active WireGuard handshake.

Host Details

Inspect a single host for detailed information:

nefia hosts show prod-web-1

The output is JSON-formatted, matching the Host struct fields. Use --output json with other commands for consistent machine-readable output.

Removing Hosts

Remove a host from your configuration and revoke its VPN peer entry:

nefia hosts remove prod-web-1

Groups

Groups are logical collections of hosts defined by tag filters. They let you target multiple hosts with a single selector.

Listing Groups

nefia groups list

Groups are defined in your nefia.yaml configuration file:

groups:
  - name: webservers
    match:
      tags:
        role: web
  - name: production
    match:
      tags:
        env: production
  - name: staging
    match:
      tags:
        env: staging
  - name: all-linux
    match:
      tags:
        os: linux

Tags

Tags are key-value pairs attached to hosts. They power group membership, target selectors, and host discovery.

Tags are assigned during enrollment or added later in configuration:

hosts:
  - id: prod-web-1
    address: 10.99.0.2
    user: deploy
    os: linux
    tags:
      env: production
      role: web
      region: us-east-1
    vpn:
      public_key: "aB3d...x7Yz="
      endpoint: "203.0.113.10:51820"
      local_endpoint: "192.168.1.50:51820"  # hairpin NAT fallback
      vpn_addr: "10.99.0.2"
      status: active

Target Selectors

Most Nefia commands accept a --target flag to specify which hosts to operate on. There are four selector types:

Single Host

Target a single host by name:

nefia exec --target host:prod-web-1 -- uptime

The shorthand --host flag also works:

nefia exec --host prod-web-1 -- uptime

Group Selector

Target all hosts in a named group:

nefia exec --target group:webservers -- systemctl status nginx

Tag Selector

Target hosts matching a specific tag:

nefia exec --target tag:env=production -- df -h /

All Hosts

Target every enrolled host with an active VPN connection:

nefia exec --target all -- hostname

Validating Configuration

Run a configuration validation check to catch errors before they affect operations:

nefia validate

Add the --target flag to test actual VPN connectivity to selected hosts:

nefia validate --target all

This attempts a VPN connection to each matched host and reports success or the error encountered.

System Status

Get a high-level overview of your Nefia setup with per-host connectivity:

nefia status

The host table probes each active VPN peer with a TCP dial (3-second timeout). Use --no-check to skip connectivity probing for faster output:

nefia status --no-check

For deeper diagnostics, use nefia doctor to run comprehensive health checks covering config, auth, audit, VPN, and connectivity:

nefia doctor

Agent Management

Check the agent version running on target hosts:

nefia agent version --target all

Upgrade agents on hosts running older versions:

nefia agent upgrade --target tag:env=staging

Version Pinning

Pin an agent to a specific version to hold back a known-good release while testing newer versions on other hosts:

nefia agent pin 1.2.0 --target host:prod-web-1

Pinned agents will not auto-update beyond the specified version. This is useful when you want to validate a newer agent release on staging hosts before rolling it out to production.

Remove the pin to allow the agent to resume auto-updates:

nefia agent unpin --target host:prod-web-1

MCP Tools

AI agents can manage hosts programmatically:

Related