Skip to main content

Netsody Agent

The Netsody agent is a persistent local service that ensures your device remains connected to all Netsody overlay networks it has been added to.

Responsibilities​

The agent autonomously handles the local tasks required for participating:

  • Identity Management
    On first startup, the agent generates a cryptographic key pair. This process includes a CPU-hard proof of work, which may take some time to complete. The resulting public key serves as the node's identity within the network. The private key is stored locally and never leaves the device.

  • Controller Synchronization: Retrieves the network state assigned to the device by the controller and keeps the local agent state in sync with it.

  • Network Reconciliation
    Continuously compares the desired controller state with the actual system state. When differences are detected, it applies the necessary changes to bring the system into compliance. The reconciler aims to maintain Netsody network connectivity at all times. However, in some cases (e.g., due to overlay IP or subnet changes), a brief interruption in Netsody network access may occur. If the reconciler fails to reach the desired state, it will continue retrying until successful.

  • Virtual Network Interface Provisioning
    Manages the creation and lifecycle of virtual network interfaces used to connect the system to Netsody overlay networks. These interfaces (implemented as TUN devices) expose regular IP connectivity to local applications, while all traffic is transparently routed through the agent and processed according to the controller state.

  • Routing Coordination
    Installs system-level routing rules to direct specific traffic to physical IP subnets via the Netsody network. This allows access to remote physical networks that are otherwise unreachable, by having Netsody nodes act as gateways and share access to their local networks with other nodes in the overlay.

  • DNS Management
    Modifies the system's DNS settings to enable name-based communication with other overlay nodes (e.g., <node>.netsody.me).

  • Access Enforcement
    All traffic passing through the virtual network interface is subject to strict access control. For outgoing traffic, the agent checks whether the destination IP is permitted by the configured egress policies. For incoming traffic, it verifies that each packet is cryptographically authenticated, the claimed overlay IP address matches the sender's public key, and the communication is permitted by the ingress policy. This prevents overlay IP spoofing and ensures that only authorized identities can send or receive traffic. Access control follows Zero Trust principles: every packet is verified individually, and no communication is allowed without explicit authorization.

  • Connectivity: Coordinates the setup and maintenance of encrypted connectivity between peers. Direct paths are used when possible, with fallback transports used when restrictive networks prevent direct communication.