> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/gateway/knowledge-base/knowledge-base-articles/agent-tunnel.md). # Agent tunnel Configure Agent Tunnel to route Devolutions Gateway sessions through Devolutions Agent, reaching private network machines without direct connectivity. {% hint style="warning" %} **Experimental** (Devolutions Gateway and Agent **2026.2.0+**). Test before a broad rollout. {% endhint %} Agent Tunnel lets Devolutions Gateway reach machines on a private network it can't connect to directly. You install Devolutions Agent on a machine inside that network (a jump host or site server). The agent dials out to the gateway and advertises the IP ranges and domains it can reach. After that, any session you open through the gateway to one of those targets is routed through the agent automatically. Nothing changes for the user. This guide shows how to connect a gateway to an agent and route traffic through it. ### Before you start * Devolutions Gateway **2026.2.0+** and Devolutions Agent **2026.2.0+**. * The agent machine can reach the gateway over **HTTPS** (to enroll) and over **UDP on port 4433** (the tunnel). * On the gateway/firewall: allow **inbound UDP 4433** from the sites where agents run. * A Devolutions Server account that can manage the gateway. ### Enable Agent Tunnel on the gateway Edit `gateway.json`: * Windows: `%ProgramData%\Devolutions\Gateway\gateway.json` * Linux: `/etc/devolutions-gateway/gateway.json` * macOS: `/Library/Application Support/devolutions-gateway/gateway.json` ```json { "Hostname": "gateway.contoso.com", "AgentTunnel": { "Enabled": true, "ListenPort": 4433 }, "__debug__": { "enable_unstable": true } } ``` Set `Hostname` to the address agents use to reach the gateway, then restart the Devolutions Gateway service. ### Generate an enrollment string in Devolutions Server In Devolutions Server, open ***Administration*** – ***Devolutions Gateway***, select your gateway, and click ***Agent Tunnel***. Click the ***+*** button to add an agent. Enter an ***Agent Name*** and a ***Lifetime***, then click ***Generate***. Copy the ***Enrollment string***. {% hint style="warning" %} The enrollment string is a one-time secret. Keep it safe, and generate a new one if it expires before you finish. {% endhint %} ### Install the agent on the site machine Run the Devolutions Agent installer on the machine inside the private network. Enable the ***Agent Tunnel*** feature. Paste the enrollment string into ***Enrollment String***. Set the routes this agent should reach: * ***Advertise Subnets***: IP ranges (for example `10.10.0.0/24`). Leave blank to detect local subnets automatically. * ***Advertise Domains***: DNS suffixes (for example `*.example.com`). Finish the wizard. The installer enrolls the agent and tests the connection; if it can't reach the gateway, setup fails so you can fix the firewall on the spot. ### Confirm the agent is online Back in the Devolutions Server ***Agent Tunnel*** dialog, the agent should now show ***Online*** with its subnets, domains, and last-seen time. {% hint style="info" %} To retire an agent, remove it here and uninstall it on the machine. {% endhint %} ### Connect through the gateway Users don't install anything. They connect through the gateway as usual, and it routes through the agent automatically when the destination matches. In Remote Desktop Manager, open a session for a host inside an advertised range. In ***VPN/tunnel/gateway***, set the type to ***Devolutions Gateway*** and pick the gateway the agent enrolled with. Set the ***Host*** to the internal target (for example `10.10.0.20`). Connect. The session opens through the gateway and the agent. ### Troubleshooting
ProblemCheck
Enrollment fails during installEnrollment string expired or mistyped; gateway not reachable over HTTPS; Agent Tunnel not enabled on the gateway
Connection test fails at end of installUDP port 4433 to the gateway is blocked, or the gateway Hostname is wrong
Agent is Online but the session still connects directlyThe target isn't inside an advertised subnet or domain; the target is IPv6-only (use a domain instead)
Agent shows OfflineRestart the Devolutions Agent service on the site machine
To test the tunnel from the agent machine: ```bat DevolutionsAgent.exe probe ``` ### How it works The steps above are all you need to route traffic. This section is for readers who want the details behind the scenes. #### What is "advertisement", and what topology does it require? When an agent connects, it tells the gateway which IPv4 subnets (for example `10.10.0.0/24`) and DNS domain suffixes (for example `*.example.com`) it can reach. That list is the *advertisement*. The agent re-sends it periodically so the gateway always has the current picture, and the gateway keeps one route table per connected agent. Topology: * The agent makes a single outbound connection to the gateway (UDP 4433). Nothing at the site needs a public IP or an inbound firewall rule, which is why it works behind NAT. * Because the gateway is the meeting point for every connection, it must sit somewhere reachable by both the agents *and* the Devolutions Server and Remote Desktop Manager clients. If either side can't reach the gateway, routing through an agent can't work. * The gateway needs inbound UDP 4433 reachable from the agent sites, plus its normal HTTPS listener for enrollment. * The agent must have ordinary network reachability (routing + DNS) to the targets it advertises. The agent is effectively the "last hop" on the private network. One gateway can hold many agents; one site can run more than one agent for redundancy. #### Where are domains and IPs resolved? Two different things happen: 1. **Route matching (on the gateway).** When a session starts, the gateway takes the target from the session and matches it against every connected agent's advertisement: * An IP target is matched against advertised subnets. * A hostname target is matched against advertised domains (suffix match). The gateway does *not* do a DNS lookup here. It compares names. * The most specific match wins (a subnet match outranks a domain match; a longer domain suffix outranks a shorter one). * When two online agents advertise the same route (an equally specific match), the gateway prefers the one whose advertisement arrived most recently, so the latest one effectively wins. It's tried first, and the gateway falls back to the others only if that agent can't complete the connection. This means there is no fixed "primary/backup"; whichever agent (re)connected or refreshed its routes last takes over. * If nothing matches, the gateway connects directly, exactly as it did before Agent Tunnel existed. 2. **Actual name resolution (on the agent).** The gateway hands the target (host and port) to the chosen agent, and the agent resolves the DNS name and opens the connection from inside the private network. This is the whole point: the site's own DNS resolves names the gateway can't see. It also means you advertise domains for hosts that only exist in internal DNS, and subnets for hosts you address by IP. Because subnet matching is IPv4-based today, reach an IPv6-only host by advertising a domain that covers it instead. #### How is it kept safe? * **Enrollment** uses a short-lived enrollment string generated in Devolutions Server. It's only a bootstrap credential, not the long-term trust. * The agent generates its own key pair locally and only sends a certificate request to the gateway. The private key never leaves the agent machine. * The tunnel is QUIC with mutual TLS: the gateway authenticates the agent by its certificate, and the agent authenticates the gateway. On top of that, the agent pins the exact gateway identity it saw at enrollment, so a mis-issued or rogue certificate authority still can't impersonate the gateway. * The agent enforces its own allow-list: it refuses to open a connection to anything outside the subnets and domains it advertises, even if asked. Advertisement is both a routing hint and a hard boundary. * User authorization is unchanged. Every session still needs a normal gateway authorization from Devolutions Server, Devolutions Cloud, or PAM. Agent Tunnel only changes *how* the gateway reaches the target, never *who* is allowed to connect. #### A few more things power users ask * **Why QUIC/UDP instead of TCP?** One outbound connection multiplexes many concurrent sessions and survives brief network changes (roaming, VPN blips) without dropping every session. * **Can I force a specific agent?** Yes. A session can be pinned to one agent; when pinned, it must use that agent and will fail rather than silently fall back to a direct connection. This means a pin can't be used to bypass the intended path. * **Can I turn Agent Tunnel off for a single session?** Not today. There is no per-session opt-out: the gateway decides the path purely from the destination. If a target matches an online agent's advertised routes, the session goes through that agent. To force a direct connection, the destination must not match any advertised route (or the agent must be offline/removed). * **What if the agent goes down?** It's marked Offline shortly after it stops sending updates, and the gateway stops routing to it (falling back to direct, or to another matching agent). The agent reconnects on its own with backoff when the network recovers. * **Do I have to renew certificates?** No. The agent renews its certificate automatically before it expires, as long as the service keeps running and reconnecting. * **Is the traffic still visible to the gateway?** Yes. The gateway is still the relay and terminates the session, so your existing gateway policies apply. The agent hop is transport only. * **Where do the agent's files live?** Under `%ProgramData%\Devolutions\Agent\` on Windows (certificates in the `certs` subfolder). You normally never touch these, since the installer and Devolutions Server manage them. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.devolutions.net/gateway/knowledge-base/knowledge-base-articles/agent-tunnel.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.