Getting started

StepForge is a plain Node/TypeScript app — no build step, no cloud account, no config file to fill in before your first run. Clone the repo and pick one of the two ways to run it below.

Clone the repo linked on the Repo page and you're ready to go — no account or access request needed.

Run via Docker (recommended)

The Docker image bundles Node, Playwright, and its browsers, so generated tests run headlessly with no extra setup.

docker compose up -d --build

If your user id/group id isn't 1000/1000 (check with id -u / id -g), create a .env file next to docker-compose.yml with:

STEPFORGE_UID=<your id -u>
STEPFORGE_GID=<your id -g>

so files the container writes come out owned by you instead of falling back to 1000:1000 — no need to edit docker-compose.yml itself, on this or any other machine.

Run locally

npm install
npm run dev

Runs directly via tsx, no compile step.

Either way

Open http://localhost:3300. The running app's own /info page has a fuller walkthrough of how blocks, groups, and tests fit together — see also the Info page here for the short version.

2FA / TOTP-protected flows

If a test needs to get past a two-factor login, add a "Fill TOTP code" action at the relevant step — there's nothing to fill in yourself. On the very first run, that step is what actually links the authenticator, so it's the one moment the secret's own QR/setup screen is ever shown — StepForge scans the page right there and stores what it finds automatically. Every run after that, it generates a fresh code from the stored secret instead.

Fully headless throughout.