Managing Profiles

Two concepts keep your agent focused: scenarios and profiles.

Scenarios describe what to test. Profiles describe where to test and how to access it.

Architecture of Profiles

Profiles are made up of three components:

• endpoint
• auth
• settings

The endpoint is where the test runs. Auth and settings define how the browser verification agent gets in.

You can create as many profiles as you need.

Endpoint

Endpoints keep Ranger’s browser agent focused on the environment you want to test. For local development, this is usually a localhost host and port where your app is running. The browser agent is restricted to this endpoint, which helps prevent your coding agent from seeing a staging or prod URL in the codebase and attempting to test that instead.

In some cases, the goal is to verify behavior in a non-local environment. A profile can be set up for a remote endpoint as well.

The endpoint needs to include a URL protocol (usually http:// or https://).

Example endpoints:

• http://localhost:3000
• https://staging.example.com

Auth

Many testing scenarios require a logged-in user. Asking you to log in every run defeats the purpose of autonomous testing. In some cases, basic username/password auth could live in a .env file, but many apps use SSO, 2FA, or magic link login.

Instead, Ranger opens a headed browser when you create a profile. You log in once, and Ranger saves the cookies and session state for each test run. This handles more complicated auth reliably.

Cookies expire, so profile auth goes stale over time. For most apps this is fine during a coding session. For background agents and CI, plan to refresh auth when it expires.

Custom Login Instructions

If your app has short-lived cookies or tokens that expire too quickly for saved auth to work, you can provide loginInstructions instead. This tells the browser agent how to authenticate before each verification run — for example, by hitting a local debug endpoint that issues fresh credentials:

ranger profile config set local loginInstructions "Navigate to http://localhost:3000/api/debug-auth?email=test@example.com. Copy the token from the JSON response. Run in the browser console: localStorage.setItem('auth_token', '<the-token>'). Refresh the page."

The agent follows these instructions as a mandatory first step before every verification. You can use ${VAR_NAME} syntax to reference environment variables. This approach works alongside or instead of saved auth state — if both exist, the agent will execute the login instructions regardless.

Settings

Settings fine-tune browser behavior per profile. Update any setting with:

ranger profile config set <profile> <key> <value>

Key	Type	Description
headless	true/false	Run the browser in headless (no GUI) or headed (visible) mode. Headed is useful for observing verification firsthand.
allowInsecureLocalhost	true/false	Allow localhost content in deployed environments for micro frontend workflows (e.g. single-spa). Warning: this relaxes browser security (disables same-origin protections / allows insecure mixed content) and should be used only for local development, not CI or production verification. Also available as --allow-insecure-localhost on profile add, profile update, and setup.
userAgent	string	Override the browser user agent. Useful for bypassing bot protection.
storageState	path	Path to a Playwright storage state file (cookies/localStorage). Usually managed automatically by profile auth.
cdpEndpoint	URL	Chrome DevTools Protocol endpoint for Electron apps or existing browsers (e.g. http://localhost:9222).
loginInstructions	string	Natural language instructions the agent follows to authenticate before each verification run. See Custom Login Instructions below.
header.<name>	string	Custom HTTP header sent with every request (e.g. header.Authorization). Supports ${VAR} syntax for env vars.
setupHeader.<name>	string	HTTP header sent only during the ranger profile add auth browser session, not during test runs. Useful for bypassing login protection (e.g. Cloudflare Turnstile) without affecting third-party requests. Also available as --setup-header on profile add.

Active Profile

A single profile is set as active and used as the default for ranger go, unless you pass another profile via --profile. Use ranger profile use <name> to switch and ranger profile ls to see what is available.

Local vs CI Profiles

Local profiles are meant for day-to-day development by a single user and the auth is stored in plaintext. This is convenient and fast, but not safe to share. They’re added to a ranger-specific .gitignore to prevent them from being committed to version control.

CI profiles are meant for pipelines and other shared usages. The auth file is encrypted and safe to commit. Use the --ci flag when adding the profile and in CI or the remote environment, running ranger setup [token] will decrypt it.

Adding and Updating Profiles

Adding (interactive)

1. Run ranger profile add <name>.
2. Enter the base URL when prompted.
3. A browser opens. Log in to the account you want the agent to use.
4. Close the browser to save the profile.

Ranger sets the new profile as active. Your app should be running before you start.

Adding (non-interactive)

Pass --url to skip the interactive prompt. The CLI checks reachability — use --force to bypass. A browser still opens for auth (agents should background this and notify the user). Use --skip-auth to skip auth entirely.

ranger profile add local --url http://localhost:3000
ranger profile add local --url http://localhost:3000 --force       # skip reachability check
ranger profile add local --url http://localhost:3000 --skip-auth   # no browser auth

Updating

Update a profile when auth expires or you need a different user.

Run ranger profile update <name>. Ranger opens a browser with your current session if available. Log in again if needed, then close the browser to save the new auth. For CI profiles, this writes a new encrypted auth file.

Electron and Desktop Apps

Ranger can test Electron apps and other desktop applications that expose a Chrome DevTools Protocol (CDP) endpoint.

Electron apps don’t have an HTTP URL — they’re native desktop processes. Instead of navigating a browser to a URL, Ranger connects to the app’s already-running Chromium renderer directly over CDP. This gives the browser verification agent full access to the app’s UI: it can take snapshots, click buttons, type text, and take screenshots, just like with a web app.

How to set up an Electron profile

1. Start your Electron app with remote debugging enabled:

your-electron-app --remote-debugging-port=9222

Any port works. The app must be running before Ranger connects.

2. Add a profile using the --cdp-endpoint flag:

ranger profile add my-electron-app --cdp-endpoint http://localhost:9222

Because there’s no URL to log into, --cdp-endpoint skips the URL reachability check and browser auth flow entirely. No browser opens during setup.

3. Run verifications normally:

ranger go --scenario 1

The browser agent connects to your running Electron app via CDP, takes a snapshot of the current UI state, and starts interacting with it.

Differences from web profiles

	Web profile	Electron (CDP) profile
Setup	URL + browser login	CDP endpoint only
Auth	Saved cookies	Not applicable
Agent start	Navigates to base URL	Snapshots the existing app state
URL restriction	Locked to base URL	No URL constraint

Because the app is already running and connected, the agent skips navigation and goes straight to interacting with the UI.

Limitations

Saved login sessions are not supported in CDP mode. With web profiles, Ranger captures your login (cookies, localStorage, sessionStorage) and replays it into a fresh browser on each run. This isn’t possible with Electron apps — Ranger attaches to an already-running process rather than launching a new browser, so there’s no way to inject a saved session before the app starts.

If your Electron app requires a logged-in user, handle that at the application level before Ranger connects (e.g., persist credentials to disk, use environment variables for auth tokens, or configure the app to skip login in development mode).

Workflows with Multiple Profiles

Testing interconnected apps

One use of multiple profiles is to handle feature reviews that involve scenarios in different but connected applications.

For instance, if your customer-facing app runs on localhost:3000 and your internal tool runs on localhost:3001, you could set up a profile for each of those endpoints and then tell your coding agent to use a specific one for each scenario.

$ ranger profile add customer-app

? What is the URL of your running app? http://localhost:3000

Saving authentication state...
✓ Created settings
  Set active profile: customer-app

  Profile "customer-app" configured

$ ranger profile add internal-app

? What is the URL of your running app? http://localhost:3001

Saving authentication state...
✓ Created settings
  Set active profile: internal-app

  Profile "internal-app" configured

Testing with different user types

Another use of multiple profiles is to run scenarios against different types of users.

As an example, if your app has free, paid, and enterprise customers and you’re adding a feature that affects all of them, create a profile for each user type. All profiles can point at the same endpoint. Use the Authentication Setup step in the browser to log into a different account for each.

Prompt your coding agent to use each of the profiles for a different scenario so that you can see each one in the Feature Review UI.