Do I need to install an agent on each target PC?+
Yes, every target PC requires the lightweight nefia-agent. All connections go through WireGuard VPN tunnels with no direct SSH access. Register agents by running `nefia vpn invite` on the operator side and `nefia-agent enroll` on the target side.
Which operating systems are supported?+
macOS (15+), Windows (11+), and Linux (Ubuntu 22.04+, Debian 12+, Fedora 38+) are supported for both operator and target PCs. ARM64 and AMD64 architectures are both supported.
Does it require root or admin privileges?+
No. The WireGuard VPN runs entirely in userspace via gVisor netstack — no kernel modules or root privileges needed on the operator side. Target PCs only need SSH enabled.
Does it work behind NAT or firewalls?+
Yes. Nefia automatically classifies NAT type (EIM/EDM/CGNAT) and selects the optimal connection strategy. STUN discovers your public endpoint, and for strict NAT or firewalls, the DERP relay provides an immediate WebSocket-based fallback that auto-upgrades to a direct path when possible. Hairpin NAT is handled via automatic local endpoint discovery. Captive portal detection prevents futile connection attempts in restricted networks.
Where does my data go?+
All data stays on your machines. VPN tunnels are end-to-end encrypted with WireGuard (Curve25519 + ChaCha20-Poly1305), and audit logs are stored locally in append-only format. The DERP relay is used at connection start for immediate connectivity and during enrollment, but auto-upgrades to a direct peer-to-peer path when possible. Even while traffic passes through the DERP relay, it remains end-to-end encrypted with WireGuard — the relay cannot inspect or modify your data.
What happens if the connection drops?+
The agent automatically reconnects with an adaptive watchdog that detects failures in 2 consecutive checks and triggers immediate tunnel rebuilds when network interfaces change. It runs as a system service (launchd on macOS, systemd on Linux, Windows Scheduled Task) with exponential backoff. After consecutive rebuild failures, the watchdog enters a cooldown before retrying — it never gives up permanently. Network monitoring detects IP address changes and triggers proactive reconnection before the tunnel times out. Multipath active-backup keeps a secondary path ready for instant failover. On the operator side, a circuit breaker distinguishes transient errors from persistent failures and connection health checks run with configurable timeouts. Send SIGHUP for live config reload (macOS/Linux) without restarting the service, and run `nefia-agent status` to check agent health at any time.
How does Nefia keep operations safe?+
It combines Trust On First Use (TOFU) host key verification over VPN, session root sandboxing, policy rules (per-role command/path/host restrictions), device posture checks, mTLS gateway for MCP connections, and append-only audit logs with hash-chain integrity. For sensitive operations, the MCP approval workflow pauses AI agent actions until a human approves via the TUI dashboard. Just-In-Time (JIT) access grants temporary elevated privileges with automatic expiry. Multi-host exec commands show a preview and require confirmation before running, and `--dry-run` lets you preview target resolution without executing.
How is VPN traffic encrypted?+
Nefia uses WireGuard with Curve25519 key exchange and ChaCha20-Poly1305 encryption — the same algorithms as kernel WireGuard. SSH inside the tunnel uses hardened key exchange (curve25519-sha256, ECDH only — no legacy DH groups) and authenticated MACs (hmac-sha2-256-etm) with lightweight ciphers (ChaCha20-Poly1305, AES-256-GCM) to minimize double-encryption overhead.
How are credentials stored?+
Private keys and auth tokens are stored in your OS keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager). When the keyring is unavailable (headless servers, CI), a local file encrypted with AES-256-GCM is used as fallback. Plaintext credentials are never written to disk. Agent tokens are 256-bit cryptographically random values, also stored in the OS keyring, with a 90-day TTL and automatic background rotation every 24 hours as expiry approaches. The agent checks config file permissions at startup and warns if the file is world-readable when it contains a plaintext key.
Are audit logs tamper-proof?+
Audit logs are append-only JSONL with SHA-256 hash-chain integrity — each record links to the previous one. Records are also signed with HMAC-SHA256, so any modification or deletion is detectable. Logs can be forwarded in real time to Splunk, Datadog, or a custom webhook endpoint via the built-in SIEM integration for external retention and alerting.
How does the invite token work?+
Invite tokens are signed with HMAC-SHA256 (key derived via HKDF from the operator's WireGuard private key) and include a single-use nonce for replay protection. Nonce lookups use an optimized index for fast validation at scale. Tokens expire after a configurable TTL (default 24 hours) with proportional grace periods based on token lifetime. Enrollment uses TLS 1.3 for the handshake with a progress countdown displayed during the process. Use `nefia vpn token-info` to inspect a token's expiry, target host, and remaining validity.
Can I restrict what commands or paths are accessible?+
Yes. The built-in policy engine supports regex-based allow/deny rules for commands, file paths, and host access. You can define RBAC roles with different permissions and switch between warn and enforce modes. Policy changes take effect immediately via hot-reload. For temporary elevated access, Just-In-Time (JIT) grants let operators request time-limited privileges that auto-expire. Use `nefia policy test` or the batch variant to pre-check whether an operation would be allowed before executing.
Are binaries signed?+
Yes. macOS binaries are code-signed with a Developer ID certificate and notarized by Apple. Windows binaries are Authenticode-signed with a SHA-256 code signing certificate. All binaries include an Ed25519 signature that the agent verifies on startup and during auto-updates, ensuring you're running authentic, untampered builds.
Can I automate Nefia from AI tools?+
Yes. Running `nefia mcp serve` exposes 200+ MCP tools, allowing AI agents like Claude to execute commands, transfer files (including large files up to 3 GB via streaming), run multi-step playbooks, gather system facts, manage queues, diagnose connectivity, and orchestrate targets safely at scale. The MCP server performs early parameter validation and returns domain-specific errors (e.g., FILE_NOT_FOUND, PERMISSION_DENIED) as structured isError content with actionable troubleshooting hints, so AI agents can self-diagnose failures and retry intelligently.
Does Nefia work with OpenClaw?+
Yes. Register Nefia as an MCP server in your `openclaw.json` and OpenClaw gains access to all 200+ Nefia tools. Because OpenClaw runs autonomously 24/7, we recommend enabling approval workflows (`mcp.approval.enabled: true`) and strict policy rules (`policy.mode: enforce`) to keep operations safe. See the OpenClaw Integration guide in our docs for detailed security hardening steps.
Can I review actions before execution?+
Yes. Use `nefia plan exec` to generate a plan JSON, review it, then run `nefia apply` to execute. For interactive use, `nefia exec` targeting 2+ hosts shows a preview and requires confirmation. The `--dry-run` flag resolves targets and checks policy without executing. For AI agents, the MCP approval workflow pauses destructive operations until a human approves via the TUI dashboard. In non-TTY environments (scripts, CI), pass `--yes` to skip the interactive prompt.
What are the differences between plans?+
The Free plan is built for personal use: up to 2 hosts in a single-user workspace. The Team plan ($8/member/month) unlocks unlimited hosts, unlimited members, and shared team collaboration. The Enterprise plan adds invoice and annual billing, a dedicated support engineer, and priority support — contact sales for details.
What ports do I need to open?+
Nefia uses UDP port 51820 for WireGuard by default (configurable). If you use `--stun`, no manual port forwarding is needed in most cases. When using the DERP relay, only outbound WSS (port 443 or 8443) is required — no UDP port forwarding is needed at all. SSH traffic flows inside the VPN tunnel, so port 22 is only used on the local VPN subnet.
How do I troubleshoot errors?+
Nefia includes a built-in error code registry. When an operation fails, the error message includes a structured code like E2001. Run `nefia explain E2001` to see a detailed description and step-by-step resolution instructions. Use `nefia explain --list` to browse all registered error codes. For VPN connectivity issues, run `nefia vpn diagnose` to measure per-host latency (warns above 500 ms, errors above 2 s) and detect VPN subnet route collisions. Run `nefia doctor` for a comprehensive health check covering configuration, VPN, and audit subsystems. The documentation site also has a complete Error Codes reference page.
What is the DERP relay?+
DERP (Designated Encrypted Relay for Packets) is a WebSocket-based relay server that provides immediate connectivity for peers behind strict NAT or firewalls. Nefia uses a relay-first architecture — connections are established through the DERP relay instantly, then automatically upgrade to a direct peer-to-peer path when possible. All traffic through the relay remains end-to-end encrypted with WireGuard. You can use the managed relay or deploy your own with the `nefia-derp` binary for full control over relay infrastructure.
How does agent log rotation work?+
The nefia-agent supports automatic log rotation via the `--log-file` flag. Default log paths are platform-specific: `~/Library/Logs/nefia/agent.log` on macOS, `$XDG_STATE_HOME/nefia/agent.log` on Linux, and `%LOCALAPPDATA%\nefia\logs\agent.log` on Windows. Use `--log-max-size` (default 50 MB), `--log-max-backups` (default 5), and `--log-max-age` (default 30 days) to control rotation behavior. Old log files are automatically cleaned up.
How does device posture checking work?+
Run `nefia posture check` to evaluate target security signals — firewall status, disk encryption, OS version — against policies. In enforce mode, non-compliant devices are blocked from operations. In warn mode, issues are logged but operations proceed. Results feed into compliance reports.
How are secrets managed?+
Nefia resolves secrets at execution time from five providers: environment variables, local files, HashiCorp Vault, AWS Secrets Manager, and 1Password (via op CLI). Secrets are injected into commands and playbooks without storing plaintext in config files. Use `nefia secrets list` to see configured providers and `nefia secrets test` to verify provider connectivity.
Can I generate compliance reports?+
Yes. Run `nefia compliance report` to auto-generate compliance reports covering SOC 2 (14 controls), ISO 27001 (12 controls), or HIPAA (11 controls). Reports are built from your audit logs and configuration state, with HTML output ready for auditors. The MCP tool `nefia.compliance.report` lets AI agents generate reports programmatically.
How do agents get updated?+
Run `nefia agent upgrade --target all` to upgrade agents across your fleet remotely. Updates are verified with Ed25519 signatures. If a new agent version fails to start, automatic rollback restores the previous version. Use `nefia agent pin` to lock a host to a specific version.
What is event-driven automation?+
Nefia provides two complementary systems. Beacons run on agents and monitor conditions like disk usage thresholds, service health, or custom scripts. When a beacon fires, the operator-side reactor matches the event against rules and executes automated responses — commands, file operations, or notifications. Use `nefia.reactor.status` and `nefia.reactor.events` to monitor rule hits and recent events.
Can I schedule recurring operations?+
Yes. Use `nefia schedule create` to define cron-based recurring playbook executions. Schedules support IANA timezones, overlap policies (skip, queue, or allow concurrent runs), missed-run handling, and configurable retry counts. Manage schedules with `nefia schedule list`, `show`, `enable`, `disable`, and `history`. All 8 schedule tools are also available via MCP for AI agent orchestration.
What happens when a target host is offline?+
Commands targeting offline hosts are automatically queued for later execution when the host reconnects. Use `nefia queue list` to see pending entries, `nefia queue show` for details, and `nefia queue cancel` or `nefia queue retry` to manage them. Queued entries have a configurable TTL (default 1 hour) and expire automatically if the host does not come back online in time.
How do I deploy files to multiple hosts?+
Use `nefia push` to distribute a file to all hosts matching a target selector, or `nefia sync` to synchronize an entire directory — only changed files are transferred. Both support `--batch-size` and `--batch-wait` for rolling deployments, `--subset` for canary testing on a random subset, and `--dry-run` to preview which hosts would be affected without writing any files.
Can I record and replay sessions?+
Yes. Session recordings capture all commands and file operations in asciicast format for audit and replay. Use `nefia recording list` to browse recordings and `nefia recording show` to inspect metadata. Recordings can be deleted with `nefia recording delete` when retention policies allow.
How does batch execution work?+
The `--batch-size` and `--batch-wait` flags enable rolling execution across large fleets. For example, `nefia exec --target group:prod --batch-size 5 --batch-wait 30s` restarts a service on 5 hosts at a time with a 30-second pause between batches. Use `--subset N` to test on a random subset first, and `--rerun failure --last-job-id <id>` to retry only the hosts that failed in a previous run.
What is SSH CA certificate management?+
Nefia includes a built-in SSH Certificate Authority. Use `nefia sshca` to issue short-lived SSH certificates for hosts and users, eliminating the need to distribute and manage individual SSH keys. Certificates include principal restrictions, validity periods, and critical options. This is especially useful for large fleets where key rotation at scale is impractical.
Does Nefia support high availability?+
Yes. The operator CLI supports Raft-based clustering via `nefia cluster` for high availability. Multiple operator nodes form a consensus group with automatic leader election, log replication, and a Unix socket admin API. This ensures that if the primary operator goes down, another node takes over without manual intervention.
