Testing Private Staging URLs on BrowserStack Automate with Local Testing

Your staging URL is private, but BrowserStack needs to reach it

You have a staging environment behind a corporate firewall or a localhost server on your CI runner. BrowserStack Automate runs browsers in BrowserStack's data center, so those browsers cannot reach an internal URL unless you open a path to it. Publishing the staging site just for a test run is usually unacceptable, and it defeats the purpose of testing pre-release code.

The practical takeaway: run the BrowserStack Local binary on your build machine or CI runner. It opens an outbound tunnel to BrowserStack, and Automate sessions with local testing enabled can then reach localhost, staging, or internal URLs through that tunnel. The browsers still run on BrowserStack real devices and browsers; only the network path changes.

Start the Local binary and enable the session capability

BrowserStack Local is a downloadable executable. When you start it with your BrowserStack access key, it maintains an outbound connection to BrowserStack's tunnel endpoints. You do not need to open inbound firewall rules on your CI runner because the connection originates from inside your network.

Run the binary where your tests originate—typically the CI runner or a dedicated build host. The account access key must never be committed to version control; inject it as a CI secret or environment variable.

Example startup command

# Run on the CI runner or build machine
# Required: execute permission on the binary and outbound access to BrowserStack endpoints
./BrowserStackLocal --key "$BROWSERSTACK_ACCESS_KEY" --daemon start

Flags and binary names vary by Local version. Check the version you downloaded before pasting flags into a pipeline; an unsupported flag will cause the binary to exit instead of opening the tunnel.

Enable local testing in the Automate session

After the tunnel is running, set the local-testing capability to true in your Automate session request. The exact capability key depends on your client binding—Selenium, Playwright, Cypress, and Appium each spell it differently—so confirm the key for your binding before merging.

# Pseudocode; replace with your binding's exact capability key
capabilities = {
  "browserstack.local": true,
  "url": "http://staging.internal.example.com"
}

Verify the tunnel is actually carrying traffic

Do not assume the tunnel works because the binary started. Use this diagnostic sequence:

1. Run a minimal Automate script against the internal URL with local testing enabled. Confirm the session loads in the BrowserStack dashboard.
2. Stop the Local binary, or disable local testing in the capability, and run the same script. The internal URL should fail to load, proving the tunnel is required.
3. Inspect the BrowserStack session logs and the local-connection indicator for the session. The indicator should show that traffic traversed the tunnel rather than the public internet.

If step 2 still loads the page, the URL may be publicly reachable or DNS is resolving outside the tunnel. If step 1 fails, check corporate proxy authentication, egress allow-lists, and whether the Local binary version is still supported.

Trade-offs and limitations

• Not for production traffic. Local is intended for QA and development against private staging or localhost. Do not use it for synthetic monitoring, production smoke tests, or load testing.
• Attack surface. The tunnel connects your internal network to BrowserStack. Restrict traffic to specific domains, use forced-local mode for selected hosts, and honor proxy settings to reduce exposure.
• Version sensitivity. Local binary versions, capability keys, and supported flags differ across client bindings. Old binaries may be deprecated or lack security updates.
• Network dependencies. Corporate firewalls, proxy authentication, or egress allow-lists can break the tunnel. Verify connectivity before enabling Local in critical pipelines.

Actionable closing

Add the Local binary startup step to your CI job before the test stage, inject the access key from secrets, enable the local-testing capability for sessions that need internal URLs, and stop the binary when the job finishes. There is no configuration rollback because Local is a short-lived process; treat it like any other ephemeral service dependency.

Before you merge the change, run the verification sequence above with a real internal URL. If the session loads only when the tunnel is active, you have a safe, repeatable way to test private staging URLs on real browsers.