Test localhost and private network apps with AI

TestOptim's browsers run in the cloud, so on their own they can only open an app that is on the public internet. An app on localhost:3000, an internal host such as https://app.corp, or a staging server on a private IP address is invisible to them. The same is true of the single sign-on page many internal apps send you to before you can log in.

Teams usually work around this by deploying to a public preview, or by exposing the app through a public tunnel URL that anyone can find. TestOptim instead runs a small command on a machine inside your network and sends its browsers through that machine, with an allowlist you control.

Install the testoptim CLI on a computer that can open your app in a browser, such as your laptop, a build agent or a server in the office. Turn on Private network when you create the project (the button then reads Create and connect CLI), or later in the project's Settings. The install, sign-in and tunnel commands for the project then appear on its Knowledge page (for a new project) or under the switch in Settings.

brew install testoptim-ai/tap/testoptim
testoptim auth                      # paste a token with "Connect private tunnel"
testoptim tunnel --project <project-id> \
  --allow-cidr 127.0.0.1/32 --allow-cidr ::1/128   # only for an app on this machine

Windows installs with one PowerShell line, and containers can use the ghcr.io/testoptim-ai/testoptim-cli image. The token starts with topt_, is shown once, and can be limited to the one project the tunnel serves. When the tunnel is up, the project shows CLI connected with the machine's name and allowed hosts, and Start exploration unlocks. Leave the command running while you test and press Ctrl-C to close it.

From then on, the project's explorations, test runs and fix re-verifications all go through the tunnel. Internal URLs work the same as public ones.

By default the tunnel reaches only your project URL's host, on ports 80 and 443 plus any port in the URL. Everything else is blocked, and each blocked request appears in the CLI output; for an IP address, the line names the --allow-cidr to add. You add what your app needs:

• --allow sso.corp adds a host name. Wildcards such as *.corp work. Add your identity provider's host here, or single sign-on fails when TestOptim reaches it.
• --allow-cidr 10.20.0.0/16 allows an IP range on every port. You need it for hosts reached by IP address, and for localhost, because loopback, link-local and cloud metadata addresses such as 169.254.169.254 are blocked unless you allow them.

Host names are resolved on your machine with your own DNS, so names that only exist inside your network keep working. One caution: a CIDR rule allows every port at that address, so --allow-cidr 127.0.0.1/32 also lets the test browser reach other services on the CLI machine, such as a local database. Stop the tunnel when you aren't testing.

The CLI makes only outbound HTTPS connections on port 443: to api.testoptim.com to start the tunnel and check in every 30 seconds, and to the relay at tunnel.testoptim.com. You don't open any inbound ports or firewall holes.

If your app uses HTTPS, TLS runs end to end between the TestOptim browser and your app, and the relay sees only encrypted traffic. Plain HTTP is encrypted between your machine and the relay, but the relay can read it, so prefer HTTPS where you can.

To cut a machine off, revoke its token on the API keys page. A running tunnel stops within about 30 seconds with API token no longer valid, and the token can't open new ones. A project has one tunnel at a time, so run the CLI on one machine per project.

In a container or CI job, skip testoptim auth and pass the token as the TESTOPTIM_API_KEY environment variable from your CI secrets. That lets a pipeline bring up a private build, open the tunnel and then start a test run through the API.

docker run --rm -e TESTOPTIM_API_KEY="$TESTOPTIM_API_KEY" \
  ghcr.io/testoptim-ai/testoptim-cli tunnel --project <project-id> --allow sso.corp

If no machine has checked in for 90 seconds, the project shows The CLI disconnected, exploration stays disabled, and test runs fail straight away with Private tunnel offline rather than waiting.