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 and applies changes when they diverge. In some cases (for example after overlay IP or subnet changes), a brief interruption in Netsody network access can occur. If the reconciler fails to reach the desired state, it keeps retrying until it succeeds.

  • Virtual Network Interface Provisioning: Manages the creation and lifecycle of the virtual network interfaces that 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 traffic for specific physical IP subnets into the Netsody network. This gives access to remote physical networks that are otherwise unreachable: 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 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: 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.

Configuration​

The agent reads its local configuration from a config.toml file: its identity, the networks it participates in, and local behavior options. See Agent Configuration (config.toml) for the full reference.