Introduction

Nefia is a cross-platform remote PC management gateway. It lets you execute commands, transfer files, and manage configurations across multiple machines — all through encrypted WireGuard VPN tunnels.

Why Nefia?

Managing remote infrastructure typically involves juggling SSH keys, configuring VPNs, and writing ad-hoc scripts. Nefia consolidates all of this into a single CLI with built-in security guardrails.

Key Features

• VPN-first architecture — All connections use WireGuard tunnels. No exposed ports, no port forwarding. Hairpin NAT fallback handles same-LAN scenarios automatically.
• Cloud relay enrollment — Agents behind NAT/CGNAT enroll automatically via nefia.ai cloud relay. No port forwarding required.
• SSH Trust on First Use (TOFU) — VPN-authenticated hosts are trusted automatically on first connect. Key changes are rejected to prevent MITM attacks.
• Policy engine — Define allow/deny rules for commands and file paths using regex patterns, with RBAC role support.
• Audit logging — Every operation is recorded in an append-only JSONL log with SHA-256 hash chain verification.
• AI-native — Built-in MCP server with 207 tools across 18 categories (core, fs, ops, security, audit, automation, infra, management, composite, network, container, system-query, system-mutation, vpn, pki, policy, cluster, and agent) covering command execution, file management, host discovery, playbook orchestration, system queries, VPN diagnostics, queue management, device security, webhooks, backups, service management, network diagnostics, firewall management, container management, cluster operations, SSH CA, mTLS, and more. All tools include outputSchema definitions for predictable AI agent integration. Includes 51 workflow prompts, 22 resources (20 static + 2 templates), progressive tool discovery with compact mode (~3000 tokens vs ~27000), tool annotations, related tool cross-references, JSON-RPC rate limiting, and optional human approval workflows for sensitive operations.
• Large file streaming — Transfer files up to 3GB between hosts without memory buffering (~32KB overhead).
• System facts gathering — Collect OS, disk, memory, CPU, uptime, and network facts in a single SSH round-trip.
• Team collaboration — Create shared workspaces, invite members with role-based access (Owner/Admin/Member), and manage hosts across teams. Shared teams on the Free plan require an upgrade before invitations and dashboard host sync are enabled.
• DERP relay-first connectivity — Instant connection via WSS relay when direct path is unavailable, with automatic upgrade to direct path.
• NAT traversal intelligence — NAT classification (EIM/EDM/CGNAT), captive portal detection, and network monitoring for adaptive reconnection.
• Agent token security — 256-bit tokens with OS keyring storage and 90-day TTL auto-rotation.
• Agent log rotation — --log-file flag with platform-specific default paths and automatic size-based rotation.
• Structured error codes — Every error includes a machine-readable code (E1xxx–E9xxx) with resolution steps. Run nefia explain <code> to see detailed guidance directly in your terminal.
• Device Lock — Ed25519 cryptographic device verification prevents rogue devices from joining the VPN mesh, even if enrollment tokens are compromised.
• Just-In-Time access — Time-limited temporary access grants for policy-restricted operations, with approval workflows and audit trails.
• SSH Certificate Authority — Ed25519 CA with OS keyring storage, automatic user certificate issuance on connect, and host certificate signing.
• mTLS gateway — ECDSA P-256 mutual TLS for MCP server connections. Issue client certificates for AI agents with configurable TTLs.
• Secrets management — Unified secret resolution from environment variables, local files, HashiCorp Vault, AWS Secrets Manager, and 1Password.
• Device posture — Evaluate target security signals (firewall, disk encryption) against policies. Enforce or warn on non-compliant devices.
• Compliance reporting — Auto-generate SOC 2, ISO 27001, and HIPAA compliance reports from audit logs and configuration state.
• SIEM integration — Forward audit events to Splunk, Datadog, or custom webhooks with batching, retries, and HMAC signing.
• Event-driven automation — Agent-side beacons monitor disk usage, service health, and custom scripts. Operator-side reactor executes automated responses.
• HA cluster — Raft-based active-passive clustering with automatic leader election and state replication.
• Session recording — Record remote sessions in asciinema v2 format with terminal replay and configurable retention.
• Wake-on-LAN — Wake sleeping hosts via proxy agents on the same subnet, with auto-proxy selection and online wait.
• Host import — Bulk import from SSH config, Ansible inventory, CSV, and known_hosts.
• Code signing — Ed25519 signatures, macOS Developer ID notarization, and Windows Authenticode for all release binaries.
• Cross-platform — Supports macOS 15+, Linux (Ubuntu 22.04+, Debian 12+, Fedora 38+), and Windows 11+ as both operator and target machines.

Architecture Overview

Nefia uses a hub-and-spoke VPN topology where the operator PC acts as the hub:

Operator PC (hub)
├── WireGuard tunnel → Target PC 1 (spoke)
├── WireGuard tunnel → Target PC 2 (spoke)
└── WireGuard tunnel → Target PC 3 (spoke)

All communication flows through these encrypted tunnels. SSH runs inside the VPN, providing double-layer encryption with lightweight ciphers to minimize overhead.

Three Usage Modes

nefia exec --target my-server -- uname -a

Next Steps