Skip to main content

drasyl Agent

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

Responsibilities​

The agent autonomously handle all 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.

  • Configuration Fetching
    Periodically retrieves and parses network configurations from the specified source (e.g., local file or HTTP endpoint). If the source is temporarily unavailable or the configuration is invalid, the agent continues operating using the last known valid configuration and retries the fetch operation periodically.

  • Network Reconciliation
    Continuously compares the desired state defined in the configuration 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 drasyl network connectivity at all times. However, in some cases (e.g., due to overlay IP or subnet changes), a brief interruption in drasyl 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 drasyl 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 overlay configuration.

  • Routing Coordination
    Installs system-level routing rules to direct specific traffic to physical IP subnets via the drasyl network. This allows access to remote physical networks that are otherwise unreachable, by having drasyl 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>.drasyl.network).

  • 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.

  • P2P Connectivity
    Coordinates the setup and maintenance of encrypted tunnels between peers. Direct connections are established when possible. If that fails, the agent falls back to relayed communication via super peers or TCP encapsulation over port 443. Connection attempts are retried continuously as long as communication is required.