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, VPN tunnels, and brittle automation scripts. Nefia consolidates all of this behind a local operator daemon that exposes a typed gRPC runtime over WireGuard, so every target operation goes through a single secure, auditable path.

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.
• Mutual agent authentication -- Agents are bound to the operator daemon by 256-bit tokens that rotate automatically every 24 hours, with mTLS between the operator daemon and each target agent. There is no shared SSH key material to manage.
• 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 200+ tools across 20 categories (core, fs, ops, security, audit, automation, management, composite, network, container, system-query, system-mutation, vpn, pki, policy, cluster, browser, desktop, proc, and workspace) 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 daemon 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.
• Agent-native process runtime -- Spawn, attach to, and manage long-lived remote processes directly on targets via the nefia proc subcommand without SSH session semantics. Supports PTY allocation, stdin piping, signal delivery, and process reconnection after operator disconnects. Processes survive disconnections and retain output for 24 hours.
• Browser automation -- Control a managed Chromium instance on any target through nefia browser or MCP tools. Navigate, click, fill forms, upload files, capture screenshots, and stream console logs without installing an AI model on the target.
• Desktop automation -- Observe, assist, or fully control the target desktop via nefia desktop. Screen capture, pointer control, keyboard input, clipboard access, and window management run through the daemon with approval gates for privileged actions.
• Durable workspaces -- nefia workspace binds a team, host, and root directory into a first-class primitive that survives CLI invocations and daemon restarts. Processes, browser sessions, and file operations anchor to a workspace so AI agents and humans share the same durable state.
• Operator daemon -- nefia-operatord is a local background service that owns durable workspace state, multiplexes CLI, TUI, and MCP clients, coordinates approval workflows, and manages the WireGuard overlay. Install it with nefia daemon install on any supported platform.
• 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 topology where the operator PC runs the local nefia-operatord daemon. CLI, TUI, and MCP clients all talk to this local daemon, and the daemon is the only process that ever opens a connection to a target.

CLI / TUI / MCP clients
        |
        v
nefia-operatord (local daemon)
        |
        |  mutual-auth gRPC
        |  over WireGuard
        v
nefia-agent on each target
  (exec, files, processes,
   browser, desktop runtime)

All communication flows through the encrypted WireGuard overlay. The operator daemon owns durable workspace state, handles reconnection, and routes every request to the target agent's typed gRPC runtime on port 7222. SSH is not in the hot path for V2 operations, interactive nefia ssh sessions connect through the same tunnel.

Three Usage Modes

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

Next Steps