Skip to main content


The agent component acts as a proxy, representing the client by forwarding packets to and from targeted hosts within the local network. Its role is pivotal in ensuring accurate packet forwarding between the client and the designated hosts.

Agents can be installed on a variety of devices, including routers, mobile devices, personal computers, or cloud-based virtual machines, depending on the specific use case.

Currently, the agent supports WebSockets via both HTTP and HTTPS protocols, as well as QUIC for peer-to-peer connectivity as the underlying transport layer, ensuring secure and efficient communication. Additionally, it offers a convenient capability: the ability to configure it for the direct publication of a web server to the gateway. This eliminates the need for client intervention. When a request for the published domain name reaches the gateway, it is redirected to the agent, which then forwards it to the web server for processing.

To enhance security measures, the agent provides an option for end-to-end encryption of requests and responses. This introduces an additional layer of safeguarding for sensitive data during transmission. Importantly, this feature remains optional, granting users the flexibility to adjust the security level according to their specific requirements.


Agents must have a unique name for each user. Otherwise, if a new agent connects with the same name, the old agent will be disconnected.


At minimum, the agent needs to be configured with the address of the gateway and a token. The token can be generated using the Token Generator component. Additionally, the agent can be configured to publish a web server to the gateway; the publish token is a configuration element that the gateway uses to determine which domain should be published and mapped to which agent and host. Using the key is optional, and it is employed for end-to-end encryption.

- !SelfHosted # Self hosted endpoint, more options coming soon
gateway: gateway.domain.example:443 # address of the gateway
token: eyJ0eX....kNHYQ_4 # token for authentication
- eyJ0eX....kNHYQ_4 # token for publishing webserver (optional)
#protocol: Wss # Wss or Ws (default: Wss)
# e2ee:
# - !PassPhrase # Enabling end to end encryption (optional)
# phrase: "your_key" # key for end to end encryption
# policy: Lax # Lax or Strict (default: Lax) Lax allows clients to connect without a key, while Strict requires a key

Default Configuration Paths

The agent can load configuration from a custom path using the -c or --config flag or from its default paths.

The default paths are as follows:

  1. Next to the agent executable file with the name agent.yaml
  2. In the operating system's configuration directory within a folder named .narrowlink, with the file named agent.yaml

Example path:

  1. In the operating system's configuration directory within a folder named narrowlink, with the file named agent.yaml

Configuration paths for different operating systems:


To explore more features and options, refer to the Extended Tutorial section or experiment with different command line options.