Test a Localhost App With AI (No Deploy)

Hosted testing usually assumes that a cloud browser can reach your application. That creates friction during local development: deploy to staging, wait for a build, expose a tunnel, then test.

AegisRunner’s default local mode reverses that arrangement. The browser runs on your machine and drives localhost directly. The testing service coordinates the scan and stores the resulting evidence, but your development server does not need a public URL or inbound port.

The current local workflow

Install the CLI, start the local browser runner, then start a scan:

npm install -g @aegisrunner/cli
export AEGIS_TOKEN=aegis_xxxxxxxx

# Terminal 1: starts the browser on your machine
aegis scan-runner

# Terminal 2: scans the local app through that browser
aegis scan --local --url http://localhost:3000 --watch

The first runner launch downloads Chromium if it is not already cached. Docker is optional; a container image is available for teams that prefer it.

What stays local

In local mode:

the browser connects to localhost directly;
the application does not receive an inbound connection from AegisRunner’s cloud;
browser traffic and local login credentials stay in the runner environment;
findings, screenshots and generated test data are sent back to the project.

The model that decides what to explore still runs as part of the AegisRunner service. Do not interpret “local browser” as a fully offline product. For strict network or data-residency requirements, evaluate the self-hosted runner and enterprise deployment options.

Set credentials on the runner process rather than placing them in shell history:

export AEGIS_USERNAME=developer@example.com
read -s AEGIS_PASSWORD
export AEGIS_PASSWORD
aegis scan-runner

Then start the scan from another terminal. AegisRunner maps the identity and password values onto the discovered login form. Multi-step or non-form authentication may require a saved login configuration and fails closed when it cannot bind the login request safely.

Vite, Next.js and Nuxt

The framework plugins add a small development-only shield to the running app. Use it to test the current page or start a scan of reachable paths without leaving the browser.

The plugins do not ship in the production build. They coordinate the same local runner and project token used by the CLI.

When to use the optional tunnel

The tunnel remains available for teams that do not want to run a browser locally:

aegis scan --tunnel --port 3000 --watch

In that mode, a cloud browser reaches your app through an outbound relay. It is a different trust and performance model. Prefer local mode when you want browser traffic and credentials to remain on the development machine; use the tunnel when the convenience is worth that trade-off.

Private staging and CI

For a shared environment, choose the narrowest access method that works:

Allowlist AegisRunner’s static egress IP for cloud execution.
Run the self-hosted runner inside the private network.
Use the tunnel for a temporary developer or CI session.

Local and private-network scans use a project-scoped CI token. Keep the token in your CI secret store, not in the repository.

- name: Start local AegisRunner browser
  run: aegis scan-runner &
  env:
    AEGIS_TOKEN: ${{ secrets.AEGIS_TOKEN }}

- name: Test preview app
  run: aegis scan --local --url http://localhost:3000 --watch
  env:
    AEGIS_TOKEN: ${{ secrets.AEGIS_TOKEN }}

Adapt process startup and readiness checks to your CI environment; do not rely on a background process being ready immediately.

What the result means

A local scan explores reachable paths within its configured page and time budget. It can generate functional cases and attach accessibility, SEO, security-header, performance and visual evidence where applicable. It does not prove every route or business rule.

When writes are not authorized, the execution fence blocks unsafe requests. Mutation-capable testing requires explicit project consent and should target disposable or controlled test data.

Playwright/POM export is available on Pro and Business. The CLI and local-runner workflow itself uses a project CI token from a supported paid plan.

Start here

Read Testing behind a firewall for runner, tunnel and allowlist details, or open the localhost testing guide for the current command reference.