> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qlane.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Single repo

> Connect a single-repo Node.js app so QLane clones the PR branch, builds it, runs it in an isolated sandbox, and tests it with full shell access.

The default mode for Node.js web apps that live in a single repository. QLane clones the PR branch, builds your app, runs it in an isolated sandbox, and connects the agent.

## When to use this mode

* Your app is **one repository** (Next.js, Remix, Express, Vite, etc.).
* It runs with one command — `npm run dev`, `npm start`, or similar.
* You want the agent to test the **exact code in the PR**, not a separate preview deployment.

If your app needs a database or other services to start, jump to [Docker Compose](/connect/docker-compose). If you already build per-PR previews on Vercel, Netlify, or Cloudflare, [Existing previews](/connect/existing-previews) is usually a better fit — same coverage, no extra build time.

## Set it up

From the project page, open **Environments → New environment** and choose **Single repo**.

1. **Repository and branch.** The branch is the default to test against (typically `main`). On a PR, QLane uses the PR's head commit automatically.
2. **Install command.** Defaults to `npm install`. Swap in `yarn`, `pnpm`, or `bun` if needed.
3. **Start command.** What boots your app — for example `npm run dev` or `npm start`.
4. **Port.** The port your app listens on (`3000` for most Next.js apps).
5. **Environment variables.** Add anything the app needs to boot. Mark sensitive values as **secret** to redact them from logs.

Save.

## Enable PR testing

Back on the project page:

1. Click the **PR testing** card.
2. Select the environment you just created as the target.
3. Toggle it on.

From now on, every pull request triggers a session that uses this environment.

## What QLane does on each PR

1. Clones your repo at the PR's head SHA.
2. Provisions a fresh, isolated sandbox.
3. Runs your install command, then the start command.
4. Waits for the app to come up on the configured port.
5. Connects the agent and runs your active test cases plus any drafts generated from the PR diff.
6. Posts a GitHub check and, if anything broke, a structured review.

Typical end-to-end time: under two minutes.

## What the agent can do in this mode

In addition to a real browser, the agent gets:

* **Shell access** inside the sandbox (`bash`, `readFile`) — it can inspect logs, check files it wrote, and re-run commands.
* **Code awareness** — it reads the repo to understand failures and write better repros.
* **Deep testing** — when stuck, the agent can add temporary instrumentation, re-run, and observe. The sandbox is torn down after the session, so changes don't escape.

## Common gotchas

* **Native dependencies.** Anything that needs a system library should be in your package's install hooks. The sandbox is Linux-based; macOS-only build steps will fail.
* **Long-running builds.** If your dev server takes more than a minute to be ready, set a custom **ready check** in the environment to a URL or HTTP code the agent should wait for.
* **Required env vars.** Your app likely needs an auth secret, database URL, etc. Set them on the environment — without them the app won't boot and the session will fail before the agent even connects.