> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/enterprise-application-testing/execution/tunnels-and-private-apps.md).

# Tunnels and Private Applications

Connect a private application or browser host to ContextQA using machines, routes, health checks, remote browser profiles, and environment URLs.

> **Documentation owner:** [Deep Barot](https://contextqa.com/academy/) · **Last updated:** November 11, 2026

## Quick answer

Use **Tunnels** to enroll a machine and publish a route to an application it can reach. Verify the route health, then use its URL in the test environment. A browser host serves a different purpose: it supplies the browser endpoint used by a remote browser profile.

## Key takeaways

* A machine hosts the agent; each route identifies a target service.
* Verify route health and the application URL before starting tests.
* Use remote browser profiles when execution needs a particular browser host.

## When should I use a tunnel?

Use a tunnel for a development server, private test application, or service reachable from an approved machine but not directly from ContextQA's execution environment. The machine must remain online and able to reach the target throughout the run.

![Tunnels page explaining machine enrollment, routes, and network requirements](https://4255556216-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKlyaXxb76z3Dn47TrZkU%2Fuploads%2Fgit-blob-aafe21332aa240ad36f3d4b24253938c41b7e211%2Ftunnels-machine-route-setup.jpg?alt=media)

## Set up a machine and route

1. Open **Tunnels** and read the displayed network requirements and account allowance.
2. Choose the tunnel namespace carefully; the interface explains when it becomes fixed.
3. Select **Add machine**, name the machine, and choose the appropriate operating system.
4. Follow the product's install guide on the approved machine. Treat the one-time enrollment token as a secret.
5. Confirm that the machine appears online.
6. Add a route for the target application, giving its host and port as requested. Use the actual destination; `0.0.0.0` is a listen address, not a reachable service destination.
7. Inspect the published URL and health status. Open the target and verify that it is the intended application.
8. Store the route URL in the ContextQA environment and run a small representative case.

A route may target a service on the agent machine or another permitted host it can reach. Network access still depends on routing, DNS, firewalls, and service configuration. A healthy machine does not by itself prove every route works.

## Use a browser host

For browser-host installations, follow the browser-host setup path and verify its health check. Select the associated remote browser profile in the plan's **Settings → Proxy & Remote Browser Settings**. Configure a proxy separately when the application's network path requires it.

![Plan settings with proxy and remote browser selectors](https://4255556216-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKlyaXxb76z3Dn47TrZkU%2Fuploads%2Fgit-blob-aeb3ead3f239e54577117738c9cffc7a7ddc4258%2Fplan-proxy-remote-browser.jpg?alt=media)

If a profile is in use, inspect the linked plans or cases before deleting or replacing it. Use [proxy and remote browser profiles](https://learning.contextqa.com/enterprise-application-testing/execution/proxy-and-remote-browser-profiles.md) for detailed precedence and scope.

## Troubleshooting

| Symptom                              | Inspect                                                                       |
| ------------------------------------ | ----------------------------------------------------------------------------- |
| Machine remains offline              | Agent service, enrollment result, outbound network requirements               |
| Machine online, route unhealthy      | Target host/port, local service, DNS, firewall, and health result             |
| Open or Use is disabled              | Route readiness and health; wait for the next check or resolve the error      |
| Browser host fails but app URL opens | Browser endpoint health and selected remote browser profile                   |
| Tests still target an old URL        | Environment selection and fixed addresses embedded in steps                   |
| Install flow expires                 | Obtain a new enrollment flow through the product; do not reuse expired tokens |

## Frequently asked questions

### Does publishing a route sign the application in?

No. Network reachability and application authentication are separate. Configure an [auth profile](https://learning.contextqa.com/enterprise-application-testing/ship/auth-profiles.md) or reusable prerequisite for the intended role.

### Do I need a separate machine for every route?

The product supports multiple routes on a machine, subject to the displayed allowance. Keep each route's destination and health explicit.

Next: [Environment and data management](https://learning.contextqa.com/enterprise-application-testing/web-testing/environment-data-management.md) · [CI/CD release gates](https://learning.contextqa.com/integrations-and-developer-tools/integrations/ci-cd-release-gates.md).


---

# 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://learning.contextqa.com/enterprise-application-testing/execution/tunnels-and-private-apps.md?ask=<question>&goal=<user_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.
