Agent

The nefia-agent binary runs on target PCs and establishes a WireGuard VPN tunnel back to the operator. Once enrolled, it maintains a persistent connection, forwards SSH traffic, and monitors its own health automatically.

Supported Platforms

Installation

curl -fsSL https://www.nefia.ai/install-agent.sh | sh -s -- --token '<INVITE_TOKEN>'

Agent Binary Commands

The nefia-agent binary provides the following subcommands:

Global Flags

Enrollment

Enrollment pairs the agent with an operator using a single-use, HMAC-SHA256 signed invite token. For cloud relay enrollment, agent tokens are issued via a 2-phase bootstrap code exchange to prevent token replay if the enrollment response is intercepted.

Enrollment Flow

nefia vpn invite --name staging-server --os macos --stun

curl -fsSL https://www.nefia.ai/install-agent.sh | sh -s -- --token '<INVITE_TOKEN>'

2-Phase Bootstrap Code Exchange (Cloud Relay)

When enrollment uses the cloud relay, agent tokens are not issued directly. Instead, the operator receives a short-lived bootstrap code and exchanges it for the actual agent token in a separate API call. This happens automatically within the operator CLI.

Security properties:

• Short-lived: The bootstrap code expires after 5 minutes, limiting the replay window.
• Single-use: The enrollment session transitions from completed to consumed atomically. A second exchange attempt is rejected.
• Host-bound: The expected_host_id set during session creation must match the agent that actually completed enrollment, preventing a different agent from claiming the token.
• Transparent to users: nefia-agent enroll and the operator CLI handle both phases automatically. The user experience is unchanged.

Enroll Flags

Cloud Relay Fallback

When the agent cannot reach the operator directly (NAT, CGNAT, firewall), enrollment automatically falls back to the cloud relay:

Agent → HTTPS → nefia.ai (relay) ← HTTPS ← Operator

The fallback is transparent -- nefia-agent enroll first tries a direct TCP connection (10 second timeout), and if that fails, uses the cloud relay via nefia.ai. Only WireGuard public keys and metadata are exchanged through the relay; private keys never leave the device.

Enrollment Error Messages

When enrollment fails, the agent receives a categorized error message to help diagnose the issue:

Enrollment Response Size Limit

Enrollment API responses are limited to 1 MB (MaxEnrollResponseBytes). Responses exceeding this limit are rejected to prevent memory exhaustion from malicious or malformed relay responses.

Rate Limiter Behavior

The per-IP rate limiter uses deterministic eviction when the limiter table is full. It evicts the oldest entry by lastSeen timestamp, preferring entries that still have available tokens over those that are currently rate-limited. This ensures that active, well-behaved clients are not evicted in favor of rate-limited ones.

Configuration

The agent stores its YAML configuration at:

• All platforms: ~/.nefia/agent.yaml (i.e. $HOME/.nefia/agent.yaml on macOS/Linux, %USERPROFILE%\.nefia\agent.yaml on Windows)

Beacon Configuration

The beacons section configures agent-side event monitoring. Events are sent to the operator's reactor via TCP.

beacons:
  disk_usage:
    enabled: true
    interval: "5m"
    warning_percent: 80
    critical_percent: 90
    paths:
      - "/"
      - "/home"
  service_check:
    enabled: true
    interval: "30s"
    services:
      - nginx
      - postgresql
  scripts:
    - name: "custom-check"
      command: "/opt/scripts/check.sh"
      interval: "10m"

Peer Entry Fields

Each entry in the peers array configures a WireGuard peer (operator):

Config Validation

On startup, the agent runs validateAgentConfig() to check all required fields:

• private_key: Must be present (plaintext base64 or keyring: reference).
• address: Must be a valid CIDR notation (e.g., 10.99.0.2/24).
• peers: At least one peer must be configured with a valid public key and VPN address.
• listen_port: Must be a valid port number (0--65535).
• derp_probe_interval: When set, must parse as a Go duration and be at least 30 seconds.

Each validation failure produces a clear error message. The agent exits immediately on validation failure.

Agent Token

Each enrolled agent receives a unique API token for cloud communication (endpoint reporting, token rotation). This token is separate from the operator's OAuth tokens and the WireGuard key pair.

Token Generation

Agent tokens are 256-bit values generated with crypto.randomBytes(32). Only the SHA-256 hash is stored server-side as an ApiToken record -- the plaintext token never persists on the server.

For direct enrollment, the operator generates the token locally and delivers it to the agent over the authenticated WireGuard tunnel.

For cloud relay enrollment, the token is issued via a 2-phase bootstrap code exchange (see 2-Phase Bootstrap Code Exchange). The server issues a short-lived bootstrap code (JWT, 5-minute TTL) when enrollment completes. The operator exchanges this bootstrap code for the actual agent token via POST /api/agent-tokens/bootstrap/exchange. The token is then forwarded to the agent over the VPN tunnel.

Token Storage

The agent stores its token in the OS keyring:

When no keyring is available (headless servers, containers), the token is encrypted with AES-256-GCM and saved to a fallback file alongside the agent config.

Automatic Rotation

Agent tokens have a 90-day TTL. The agent checks the remaining TTL every 24 hours. When the TTL drops below 7 days, the agent initiates rotation:

1. Calls POST /api/agent-tokens/rotate with its current token.
2. The server verifies the current token, generates a new token, and revokes the old one atomically.
3. The agent stores the new token in the keyring, replacing the previous value.

If rotation fails (network error, server unavailable), the agent retries on the next 24-hour cycle. The existing token remains valid until its TTL expires.

Endpoint Reporting

The agent periodically reports its public endpoint to the cloud API so operators can reach it even when IP addresses change:

• API: POST /api/hosts/[hostId]/endpoint (rate limited to 10 requests/minute)
• Trigger: Endpoint is reported after STUN discovery during startup and whenever the network monitor detects an IP change.
• Fields: The agent sends its current public endpoint, local endpoint (for hairpin NAT), and NAT type classification.

The host_id field in the agent config (set during enrollment) identifies which host record to update.

Log Rotation

The agent supports built-in log rotation via the following flags on nefia-agent run:

Default log file locations:

When the log file exceeds --log-max-size, it is rotated and compressed. Old files are pruned based on --log-max-backups and --log-max-age.

Run Command

Start the agent in the foreground:

nefia-agent run --config <PATH> [flags]

When registered as a system service, the service manager invokes nefia-agent run automatically.

On Windows, the agent runs an icacls check at startup and warns if Everyone or BUILTIN\Users has read access to the config file. On Unix, it checks file permissions (mode & 0o077) and warns if the config is readable by other users.

Service Management

Installing the Service

Register the agent as a system service so it starts on boot:

nefia-agent install-service --config <PATH>

Uninstalling the Service

Remove the system service:

nefia-agent uninstall-service [--yes]

The --yes flag skips the interactive confirmation prompt.

Platform Details

launchctl print gui/$(id -u)/com.nefia.agent

Resource Limits

SSH Host Key Verification (TOFU)

The agent's SSH host key is registered automatically during enrollment. The operator uses Trust On First Use (TOFU) semantics:

• First connection: The host key is accepted and persisted to the operator's known_hosts file.
• Subsequent connections: The key must match. A changed key causes connection rejection with a MITM warning.
• Concurrent access: A RWMutex protects the known_hosts file, allowing concurrent reads while serializing writes.

This is safe because VPN connections are already authenticated via WireGuard key pairs.

Hairpin NAT Fallback

During enrollment, the agent calls DiscoverLocalEndpoint() to detect its LAN IP address. This local endpoint is reported to the operator as a fallback for hairpin NAT scenarios where the public endpoint is unreachable from the same LAN.

The agent validates the discovered local IP against the public endpoint:

• If no suitable local IP is found, the field is left empty.
• If the local IP matches the public endpoint IP, the field is left empty (no fallback needed).
• Otherwise, the LAN address is stored in host.vpn.local_endpoint in the operator's config.

When establishing a VPN connection, the operator tries the public endpoint first. If unreachable, it falls back to the local endpoint for same-LAN connectivity.

Lifecycle

Health Monitoring and Auto-Update

The agent runs two background loops after connecting:

Health checks (watchdog) run every 60 seconds when healthy, and every 15 seconds when unhealthy (adaptive interval). If the VPN tunnel degrades, it is torn down and rebuilt with exponential backoff (5s initial, 5m cap, 2x multiplier). If all peers are stale for 2 consecutive monitoring cycles, a full tunnel rebuild is triggered. After 2 consecutive rebuild failures, the watchdog enters a 30-minute cooldown period before attempting again (it no longer gives up permanently). If peer status check fails (IPC error), all peers are treated as stale to trigger rebuild investigation. Results are reported to the operator via nefia vpn status, which shows a STALE indicator for peers with no recent handshake.

Network Monitor Integration

The agent runs a network monitor that watches for IP address changes on local interfaces (checked every 5 seconds). When a network change is detected:

1. Added and removed IP addresses are logged
2. The watchdog receives an immediate rebuild signal
3. The tunnel is rebuilt without waiting for the next health check cycle

This provides near-instant recovery after Wi-Fi reconnection, network switches, or VPN toggles on the host system.

Auto-updates are disabled by default (--auto-update-interval 0). To enable them, pass a non-zero duration such as --auto-update-interval 6h to nefia-agent run. When enabled, the agent periodically checks for new releases, downloads the binary, verifies its Ed25519 signature, replaces it atomically, and restarts the service.

Live Config Reload (Unix)

On Unix systems (macOS and Linux), sending SIGHUP to the agent process triggers a config reload:

kill -HUP $(pgrep nefia-agent)

Useful for applying key rotation or endpoint changes without service downtime. If the reload fails (e.g., invalid YAML or missing fields), the error is recorded in the health report's last_config_error field, making it easy to diagnose issues remotely via nefia-agent status or by reading agent-health.json.

SSH Log Suppression

SSH connection state changes are logged only on state transitions (reachable to unreachable and vice versa) to prevent log flooding.

Startup Summary

On startup, the agent logs a summary including peer count, auto-update status, config path, and keyring status.

Health Status

Check the agent's health from the command line:

nefia-agent status

Reads agent-health.json from the config directory and displays the current health report.

If a config reload error has occurred, a Config Error line is shown as well.

Health Report Fields

The agent-health.json file contains the following fields:

Remote Management (Operator CLI)

The operator CLI provides two subcommands for managing agents on remote hosts:

nefia agent version

Show the agent version on remote hosts:

nefia agent version [--target <selector>]

Defaults to --target all if no target is specified.

nefia agent upgrade

Upgrade nefia-agent on remote hosts:

nefia agent upgrade --target <selector> [--agent-dir <path>]

Related