# How a harness gets made

This is the text version of https://trygreenroom.dev/harness, with the same content as the page.

A harness is one file in your repo, `.greenroom/harness.yaml`. It tells Greenroom how to start your app, so every run boots a fresh copy in a machine of its own.

.greenroom/harness.yaml (The least one needs):

```yaml
version: 1
start:
  command: npm install && npm start
  ready: http://localhost:3000/
```

Greenroom copies your code into the machine, runs the command and waits for the address to answer. That is enough for a first run.

## What the file turns into

One machine per run, each part made by one line of the file.

**One machine, one run**. Deleted when the run finishes

- **Your app's image** Built once, reused until the file changes. (`image.setup`)
- **Your code** Your working tree, uncommitted changes included. (`sync`)
- **Its own data** Seeded fresh for every run. (`data.seed`)
- **The app, running** Ready when its address answers. (`start`)

**A real browser, beside the machine**

Real clicks and keys. You can watch it live.

The verifier works here

**The edge** Every call that leaves the machine.

- **Allowed** Passes to the real host. (`edge.allow`)
- **Routed** Sent to a stand-in on a port in the machine. (`edge.routes`)
- **Everything else** Blocked, and listed in the report.

## The whole file

Every block, once. Only `version` and `start` are required.

.greenroom/harness.yaml (An example, every block):

```yaml
version: 1

image:
  copy: [package.json, package-lock.json]
  setup: |
    npm ci

start:
  command: npm start
  ready: http://localhost:3000/health
  timeoutSeconds: 120

data:
  seed: node scripts/seed.js

sync:
  exclude: [/dist, /coverage]

edge:
  allow: [fonts.example.com]
  routes:
    api.payments.example: 4010

stress:
  budgetSeconds: 300
  skip: [offline]

security:
  public: [/api/markets]
  users:
    - name: ben
      headers:
        Cookie: session=ben-demo-session
```

- `image`: `setup` runs once, when the image is built. `copy` lists the files it reads.
- `start`: `command` starts the app; `ready` is the address that means it is up. Waits 60 seconds, 600 at most.
- `data`: `seed` runs once per machine, before the app starts.
- `sync`: `exclude` names what is not copied in. `node_modules` and `.git` never are.
- `edge`: `allow` lets a host through; `routes` sends one to a stand-in in the machine. The rest is blocked.
- `stress`: After the verdict, a stress pass mashes, tabs, resizes and goes offline. 120 seconds, 600 at most.
- `security`: `users` gives a second person's headers, so a locked page can be asked for by someone who should not see it.

## How one gets made

Six steps, the same for every app. Each adds one block.

### Get it to boot

Write the file above and start a run. A wrong file or a failed start says why, in words.

What a failed boot says (In Greenroom's words):

```text
# the file is wrong
start.ready "localhost:3000" is not an http or https URL,
such as http://localhost:3000/

# the app is wrong
the start command "npm start" exited before
http://localhost:3000/ answered
```

### Move the installs into the image

Installs in `image.setup` run once, not on every boot.

.greenroom/harness.yaml:

```yaml
image:
  copy: [package.json, package-lock.json]
  setup: |
    npm ci
start:
  command: npm start
```

### Give each run its own data

A seed puts every run on the same starting data.

.greenroom/harness.yaml:

```yaml
data:
  seed: node scripts/seed.js
```

### Decide every outside call

Boot once, read what the edge blocked, then allow each host or answer it from a stand-in.

.greenroom/harness.yaml:

```yaml
edge:
  allow: [fonts.example.com]
  routes:
    api.payments.example: 4010
```

### Say who else can sign in

With a second person's headers, Greenroom checks that one person cannot read another's pages.

.greenroom/harness.yaml:

```yaml
security:
  public: [/api/markets]
  users:
    - name: ben
      headers:
        Cookie: session=ben-demo-session
```

### Keep what worked

Greenroom keeps every version, and a project moves to a new one only after its app answered ready.

## Then Greenroom learns the app

Hosted Greenroom maps your app once per commit, so the verifier starts each run knowing its way around.

- **What it holds**: The pages, and what every control does when pressed.
- **How it is made**: By a crawler with no model, in a machine of its own, booted from the same harness.
- **Where it stays**: On Greenroom's side. Your report shows only what the verifier saw on your build.

## This site has one too

The file that boots this site for its own checks, as it is in the repo.

This site (wrangler dev, as production serves it):

```yaml
version: 1
# The site's own harness: Greenroom boots it in a web machine the way production serves it,
# `wrangler dev` on the real wrangler.jsonc with a local D1 (tests/support/serve.mjs), so the
# Worker's routes (the waitlist, the Markdown twins) answer as deployed.
image:
  # The packages are installed once, into the image. A change to either file rebuilds it.
  copy:
    - package.json
    - package-lock.json
  setup: |
    npm ci --no-audit --no-fund
start:
  # The plain build: no PostHog key, so a run sends no analytics.
  command: E2E_OUT=/tmp/greenroom-website node tests/support/build.mjs && E2E_OUT=/tmp/greenroom-website node tests/support/serve.mjs plain
  ready: http://localhost:8791/
  timeoutSeconds: 300
sync:
  # The pictures a pull request shows are not part of the built site, nor is what a local test
  # run leaves behind. The leading slash keeps each name to the repository's root.
  exclude:
    - /docs/screenshots
    - /test-results
    - /playwright-report
```

We test Greenroom the way it tests you: a change of ours merges only after a Greenroom run has tried it on the real app.

[Join the waitlist](https://trygreenroom.dev/waitlist)

We build Greenroom with Greenroom.
