Background Agent and CI Setup

Beta

This feature is in beta. We are actively developing background agent and CI support. If you’d like to get started using Ranger with a background agent, reach out to us and we’ll help you set it up.

This guide covers running Ranger in hosted environments, including background agents running on isolated VMs, and CI workflows (GitHub Actions, GitLab CI, etc.). The same steps apply regardless of the platform - anywhere you can run Node.js and a headless browser.

Ranger works with any coding agent that can execute bash commands — Claude Code, OpenCode, Codex, or any other agent with shell access.

How auth works without a human

CI and background agents don’t have anyone to click “log in” or tap a phone for a 2FA prompt. Ranger has three login mechanisms it uses in priority order — they’re the same ones described in Profiles → How Ranger logs into your app; the steps below are the operational bits for getting your hosted environment set up.

Your app’s situation	Strategy
No login	Skip auth — point Ranger at the URL and go.
Enterprise customer with automated login configured (any auth shape, set up with our team)	Automated login — headless, deterministic.
Login flow an agent can do (short-lived tokens, debug-auth endpoint, custom form)	Login instructions — natural language; the agent follows them.

Each path has the same structure: a one-time profile setup, then secrets in your hosted environment, then your normal CI/agent steps.

Path: Skip auth

For sites without authentication, no profile setup is needed beyond pointing at the URL.

ranger profile add public-site --url https://docs.example.com --skip-auth

Commit nothing; the profile is reachable from any environment with RANGER_CLI_TOKEN. Skip ahead to environment setup.

Enterprise customers only. Ranger logs into your app for you on every CI run and background agent; your team sets credentials as env vars.

For the full picture of what we cover and how it fits into a profile, see Automated login. The steps below are the operational bits for wiring it into your hosted environment.

1. Pick test credentials

Pick the account the hosted agent will log in as. The username doubles as the profile name, so pick something stable.

2. Make secrets available to the environment

Your environment needs these secrets:

Secret	Description
`RANGER_CLI_TOKEN`	Your Ranger API token (`rngr_...`). Used for CLI auth.
`RANGER_TEST_USERNAME`	Test account username (typically the email used to log into your app).
`RANGER_TEST_PASSWORD`	Test account password.

You’ll also need an API key for your coding agent (e.g. ANTHROPIC_API_KEY for Claude Code). How you provide these depends on your platform — GitHub repo secrets, GitLab CI variables, environment variables in a VM, etc.

3. (Optional) Smoke-test from your laptop

Before letting CI rip, run a one-shot locally to confirm the credentials work:

RANGER_TEST_USERNAME=$TEST_USER RANGER_TEST_PASSWORD=$TEST_PASS \
  ranger go --base-url https://staging.example.com \
  --notes "smoke: dashboard renders"

If that works locally, it’ll work in CI with the same secrets.

Skip ahead to environment setup.

Use this when automated login can’t model your app’s auth — short-lived tokens, debug auth endpoints, custom bootstraps.

1. Create a profile

ranger profile add preview --skip-auth --url https://staging.example.com

--skip-auth skips the browser auth step. The profile exists with no session attached; the agent will run your instructions on every verification.

ranger profile config set preview loginInstructions \
  'Navigate to ${PREVIEW_URL}/api/debug-auth?email=${TEST_USER_EMAIL} to obtain a session token.'

Plain language; ${VAR} references resolve at runtime, so credentials don’t have to live in the instructions text. The agent runs these before every verification.

3. Dynamic base URLs

If your deployment URL changes per environment (Vercel preview URLs, Heroku review apps), use ${VAR} in baseUrl too:

ranger profile config set preview baseUrl '${PREVIEW_URL}'

Same trick works for headers:

ranger profile config set preview headers.Authorization '${AUTH_TOKEN}'

4. Make secrets available

Secret	Description
`RANGER_CLI_TOKEN`	Your Ranger API token (`rngr_...`). Used for CLI auth.

Plus any env vars your instructions reference (e.g. TEST_USER_EMAIL, PREVIEW_URL, AUTH_TOKEN), and your coding agent’s API key (e.g. ANTHROPIC_API_KEY for Claude Code).

Environment Setup Steps

These are the steps your environment needs to run, in order. The commands below are plain bash — adapt them to your platform’s syntax.

1. Check out the repository

Clone with full git history (needed if you want to generate diffs):

git clone <repo>

2. Install Node.js

Ranger CLI requires Node.js 18+.

3. Install project dependencies

npm install

4. Install a virtual display (Linux only)

Ranger runs a headless Chromium browser. On Linux environments without a display server, you need Xvfb:

apt-get install -y xvfb
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99

Not needed on macOS or environments with a display server.

5. Install your coding agent and Ranger CLI

Install Ranger CLI globally, along with whatever coding agent you’re using:

npm install -g @ranger-testing/ranger-cli

# Plus your coding agent, e.g.:
npm install -g @anthropic-ai/claude-code

6. Install Chromium and authenticate

Pass your Ranger API token to the setup command. In non-interactive mode, this authenticates and installs the Playwright Chromium browser:

export RANGER_CLI_TOKEN=<your-token>
ranger setup $RANGER_CLI_TOKEN

See Authentication for all auth options.

Separating install from auth (Docker / custom images)

If you’re building a container image, you can install Chromium and dependencies at build time (no token needed), then authenticate at runtime:

# -- Build time: bake deps into the image --
FROM node:20

RUN npm install -g @ranger-testing/ranger-cli @anthropic-ai/claude-code
RUN ranger setup deps --with-deps

ranger setup deps installs Chromium without requiring authentication or a git repo. --with-deps tells Playwright to also install OS-level libraries (fonts, libx11, etc.) that headless Chromium needs on Debian/Ubuntu.

At runtime, authenticate and set up skills:

# -- Runtime: per-user or per-job auth --
export RANGER_CLI_TOKEN=<your-token>
ranger setup login --token $RANGER_CLI_TOKEN
ranger setup skills --scope user

Each subcommand runs only its phase — login handles auth, skills installs the Claude Code plugin and skill files. You can also still use ranger setup $RANGER_CLI_TOKEN to run everything at once.

7. Run a verification

If you set up automated login, set the credentials as env vars and call ranger go directly:

RANGER_TEST_USERNAME=$TEST_USER RANGER_TEST_PASSWORD=$TEST_PASS \
  ranger go --base-url $APP_URL --notes "<what to verify>"

If you set up login instructions, pin the profile and let the agent run them:

ranger profile use preview
ranger go --notes "<what to verify>"

If you’re skipping auth, just pin the profile and run:

ranger profile use public-site
ranger go --notes "<what to verify>"

8. Install Ranger skills

Install the Ranger skill files that teach your coding agent how to create feature reviews and run verifications:

ranger skillup

This places skill markdown files in .claude/skills/ (compatible with any agent that reads skill files from the project directory).

9. Configure your coding agent’s permissions

Your coding agent needs permission to run bash commands (for ranger, gh, git, etc.) and read files. How you configure this depends on your agent.

Claude Code example — write .claude/settings.local.json:

{
    "permissions": {
        "allow": ["Bash(*)", "Read(*)", "Glob(*)", "Grep(*)"],
        "deny": []
    }
}

Other agents may need equivalent configuration, or may not require it at all.

10. Run your coding agent with Ranger

Invoke your coding agent in non-interactive mode with a prompt that tells it to use the Ranger skill. The skill files teach the agent how to create feature reviews, write scenarios, and run browser verification.

Here are two possible use cases:

CI workflow: Bug bash a PR’s changes

Trigger on every pull request. The agent reads the diff, creates scenarios based on what changed, and verifies them in the browser. Results get posted as a PR comment.

claude --print "Look at the git diff for this branch against main. \
  Use the /ranger skill to create a feature review from the UI changes \
  and verify each scenario. Post results as a PR comment using gh."

Background agent: Build and verify a feature

Give a coding agent a feature task and let it implement the code, then verify its own work in the browser before reporting back.

claude --print "Read the task requirements and document a plan in docs/feature/{feature-name}.md. \
    Implement the feature in the codebase, referencing the original task for context. \
    Commit changes and push to the current branch. \
    Use the Ranger skill to authenticate against the current environment and verify the feature works end-to-end in the browser."

Refreshing authentication

Sessions refresh automatically:

Automated login: when a saved session expires, Ranger logs in again with the env-var credentials. No manual step.
Login instructions: the agent runs them on every verification, so there’s nothing to refresh. If the underlying flow changes (a new debug endpoint, a renamed env var), update the instruction text:
Terminal window
```
ranger profile config set preview loginInstructions "<updated instructions>"
```
Skip auth: nothing to refresh.

Limits

Automated login needs a one-time setup with us. If your app isn’t set up yet, use login instructions or do a one-time headed login locally and reuse the saved session in CI. Reach out and we’ll get you wired up.
Some MFA factors require a human in the moment — see Multi-factor authentication for which factors automated login can hold and which need a one-time headed login.
One profile per account. If you need different accounts, make different profiles. If you need the same account against different environments, override baseUrl per environment (see Dynamic base URLs).

Troubleshooting

The account you’re using doesn’t have automated login configured. Reach out and we’ll set it up. In the meantime, use login instructions.

Usually a bot challenge blocking the login page. If you have a header that bypasses it, set it on the profile — see Bypassing bot protection during login. If your bot protection can’t be bypassed with a header, fall back to login instructions hitting a debug-auth endpoint.

”Profile X not found”

Profile names are usually the username/email of the account. If you used automated login, the profile name is the value of RANGER_TEST_USERNAME — pass that as --profile if you need to disambiguate. Run ranger profile ls to see what’s available.

Coding agent blocks commands

Some agents sandbox tool calls by default. Make sure your agent has permission to run bash commands before invoking it. For Claude Code, this means writing .claude/settings.local.json (see step 9).

Browser fails to launch

On Linux, make sure Xvfb is running and DISPLAY is set before the agent starts. Chromium needs a display server even in headless mode on some configurations.

Vercel preview environments return 401/403

Vercel’s Deployment Protection blocks automated access to preview URLs by default. To bypass it, generate a protection bypass token in your Vercel project settings and add it as a custom header on the profile:

ranger profile config set preview headers.x-vercel-protection-bypass '<your-bypass-token>'

See Vercel’s bypass automation docs for how to generate the token.

Example: GitHub Actions Workflow

A complete workflow using Claude Code with automated login. Copy to .github/workflows/ranger-pr-verify.yaml.

Required secrets (Settings > Secrets and variables > Actions):

RANGER_CLI_TOKEN — Your Ranger API token
RANGER_TEST_USERNAME — Test account username for your app
RANGER_TEST_PASSWORD — Test account password
ANTHROPIC_API_KEY — Anthropic API key for Claude Code

name: Ranger PR Verification

on:
    pull_request:
        types: [opened, synchronize, reopened]
    workflow_dispatch:
        inputs:
            pr_number:
                description: 'PR number to verify (optional, uses current branch if empty)'
                required: false
                type: string

env:
    HUSKY: 0

jobs:
    verify:
        name: Ranger PR Verification
        runs-on: ubuntu-latest
        permissions:
            contents: read
            pull-requests: write

        steps:
            - name: Checkout repository
              uses: actions/checkout@v4
              with:
                  fetch-depth: 0

            - name: Setup Node.js
              uses: actions/setup-node@v4
              with:
                  node-version: '20'

            - name: Install dependencies
              run: npm install

            - name: Install system dependencies
              run: |
                  sudo apt-get update
                  sudo apt-get install -y xvfb

            - name: Install Claude Code and Ranger CLI
              run: npm install -g @anthropic-ai/claude-code @ranger-testing/ranger-cli

            - name: Setup Ranger CLI
              env:
                  RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }}
              run: ranger setup ${{ secrets.RANGER_CLI_TOKEN }}

            - name: Configure Claude Code permissions
              run: |
                  mkdir -p .claude
                  cat > .claude/settings.local.json << 'EOF'
                  {
                    "permissions": {
                      "allow": [
                        "Bash(*)",
                        "Read(*)",
                        "Glob(*)",
                        "Grep(*)"
                      ],
                      "deny": []
                    }
                  }
                  EOF

            - name: Run Ranger verification
              env:
                  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
                  RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }}
                  RANGER_TEST_USERNAME: ${{ secrets.RANGER_TEST_USERNAME }}
                  RANGER_TEST_PASSWORD: ${{ secrets.RANGER_TEST_PASSWORD }}
                  DISPLAY: ':99'
                  GH_TOKEN: ${{ github.token }}
              run: |
                  Xvfb :99 -screen 0 1920x1080x24 &
                  export DISPLAY=:99
                  sleep 2

                  claude --print "Look at the git diff for this branch against main. Use the /ranger skill to create a feature review from the changes and verify each scenario. Post results as a PR comment using gh."
              timeout-minutes: 30

The agent’s ranger go calls pick up RANGER_TEST_USERNAME / RANGER_TEST_PASSWORD from the env automatically — no separate profile setup step is needed in the workflow.