> 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/execution/proxy-and-remote-browser-profiles.md).
# Proxy & Remote Browser Profiles
Configure reusable proxy and remote browser profiles in ContextQA, assign them to test cases or plans, and keep connection secrets protected.
## Quick answer
Create organization-level connection profiles under **Settings → Organization Setting → Proxy** or **Remote Browser**, then select a profile in a test case or test plan. A proxy routes execution through an internal network; a remote browser sends execution to an external WebSocket browser endpoint. Remote browser profiles must pass **Test Connection** before they can be saved.
## What this page covers
{% hint style="info" %}
**Who is this for?** Administrators and SDETs who need ContextQA to reach private applications, route traffic through an approved network, or execute against a managed browser grid.
{% endhint %}
## Organization profile library
Profiles are reusable at organization scope. Create them once, then assign them from the test case or test plan that needs the connection.
| Profile | Required fields | Optional fields | Typical use |
| ------------------ | ------------------------------------------------------ | ------------------ | ----------------------------------------------------------------------- |
| **Proxy** | Name, **Proxy URL** such as `http://host:port` | Username, password | Reach an application through a corporate proxy or approved egress path. |
| **Remote Browser** | Name, **Remote Browser URL** such as `wss://host:port` | Username, password | Run against an external browser endpoint or browser grid. |
{% hint style="warning" %}
Use a dedicated automation credential with the minimum access required. Do not paste credentials into test-step text, test names, screenshots, or documentation.
{% endhint %}
## Add a proxy profile
{% stepper %}
{% step %}
### Open the Proxy section
Go to **Settings → Organization Setting**, then select **Proxy**.
{% endstep %}
{% step %}
### Enter the connection
Select **Add Proxy**. Enter a recognizable name and a proxy URL in `http://host:port` form. Add the username and password only when the proxy requires authentication.
{% endstep %}
{% step %}
### Save the profile
Select **Add Proxy**. The profile becomes available in test-case and test-plan settings.
{% endstep %}
{% endstepper %}
## Add a remote browser profile
{% stepper %}
{% step %}
### Open the Remote Browser section
Go to **Settings → Organization Setting**, then select **Remote Browser**.
{% endstep %}
{% step %}
### Enter the endpoint
Select **Add Remote Browser**. Enter a recognizable name and the WebSocket endpoint, normally in `wss://host:port` form. Add credentials only when the endpoint requires them.
{% endstep %}
{% step %}
### Test the connection
Select **Test Connection**. ContextQA enables saving only after the current URL and credentials pass the connection test. If you change the URL, username, or password after a successful test, test the connection again.
{% endstep %}
{% step %}
### Save the profile
Save the profile after the successful connection result appears.
{% endstep %}
{% endstepper %}
## Assign a profile
Choose the connection at the narrowest useful scope:
```mermaid
flowchart TD
A[Organization profile library] --> B[Test plan settings]
A --> C[Test case settings]
B --> D[Applies to cases run through that plan]
C --> E[Applies to that test case]
E --> F[Test-case selection takes precedence
when both scopes specify a profile]
D --> F
```
* Use the **test plan** setting when every mapped suite should use the same route or remote grid.
* Use the **test case** setting for a targeted exception.
* Select **None** when the case or plan should not use a saved profile.
* Requirement imports that create a plan can also expose proxy and remote-browser selections in their advanced configuration.
After assigning a profile, run a non-destructive smoke test before adding the profile to a broad regression plan.
## Secret-handling behavior
When you edit a saved profile, the password field opens blank. The stored secret is not loaded back into the browser.
* Leave the field untouched to keep the current credential.
* Enter a new value to replace it.
* If your organization rotates a password, retest the remote browser connection before saving.
This behavior reduces the chance of exposing a reusable credential in the portal or a screenshot.
## Troubleshooting
Save is disabled for a remote browser profile
Select **Test Connection**. Saving remains disabled until the current endpoint and credential values pass.
The profile does not appear in a test case or plan
Confirm that the profile was saved in the same organization, refresh the selector, and clear any search text. Profile lists are organization-specific.
The connection works locally but the ContextQA run cannot reach it
Confirm that the endpoint is reachable from the ContextQA execution environment, that the scheme and port are correct, and that network allowlists include the approved ContextQA execution source for your deployment.
## Related documentation
* [Test plans](/web-testing/test-plans.md)
* [Create test cases](/web-testing/creating-test-cases.md)
* [Environments](/execution/environments.md)
* [System configuration](/administration/system-configuration.md)
{% hint style="info" %}
**Need to test a private application or managed browser grid?** [**Book a Demo →**](https://contextqa.com/book-a-demo/) — See how ContextQA fits your network and execution architecture.
{% endhint %}
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://learning.contextqa.com/execution/proxy-and-remote-browser-profiles.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.