Blokk.
BLOKK GUIDES · GETTING STARTED

How to set up, use and test Blokk.

Start with one action you want to understand. This guide walks authorised developers through the local bot-detection lab and explains the separate, guided route for a Shopify monitoring evaluation.

Editorial review: . Local instructions describe the development checkout reviewed on that date; they do not imply that every feature is available on the hosted preview.

1. Choose your starting point.

Shopify merchants and agencies: start with the scoped monitoring evaluation and the Shopify steps below. Access is arranged with the team; there is no public self-service app installation. Hosted monitoring has been exercised on development stores; merchant production installation and public app approval remain pending. A local test does not activate protection on a store.

Developers with authorised source access: follow the local setup below from the repository root. It creates a development database and two fictional test sites. Source access and commercial self-hosting are not offered through this guide. Use only a local development environment, never a production database or a live store.

2. Install the local prerequisites.

Use Node.js 22 LTS within the supported Node 22–24 range, pnpm 10.30.2 and PostgreSQL 17 binaries. Installation needs access to the npm registry; the generic local lab needs no paid service key. Confirm Node and pnpm before installing the locked dependencies:

node --version
pnpm --version
pnpm install --frozen-lockfile

If PostgreSQL is outside the locations recognised by the setup script, set PG_BIN to its PostgreSQL 17 binary directory. Follow the repository’s configuration reference for platform-specific settings.

3. Generate configuration and start the database.

pnpm setup:env
pnpm db:local

The first command creates a protected .env with separate random secrets and refuses to overwrite an existing file. A fresh file sets LAB_MODE=true and keeps publication private. Keep these credentials out of Git, screenshots and support messages.

The database command creates an isolated PostgreSQL cluster on loopback port 55439 with a separate database and restricted role for each service. It does not install a system service. For an existing checkout, keep its configuration and start its existing cluster; do not regenerate credentials as a troubleshooting shortcut.

4. Create the local operator and link the test sites.

pnpm operator bootstrap
pnpm setup:link
pnpm db:migrate
pnpm setup:stateful

Bootstrap creates the initial workspace, local operator and Northstar test site. It saves one-time credentials in the protected .env.bootstrap file. Linking copies the test integration settings into .env without displaying their values. Store the operator login securely, then remove the bootstrap file after linking.

Migration prepares the detector and Northstar schemas. The final command prepares Quillmark, the account-based test app, and its own database and site key. Bootstrap and linking are initial setup steps; do not repeat them when simply restarting an existing lab.

5. Start Blokk and create your first assessment.

pnpm dev
  1. Open http://localhost:4000/health. Check for HTTP 200 and an available database before testing the interface.
  2. Open http://localhost:3000/app and sign in with the local operator credentials created in step 4.
  3. Open Northstar at http://localhost:3002, follow its contact form and submit fictional details. Its backend requests an assessment when processing the submission.
  4. Return to Events in the console, select the Northstar site and open the new event. Inspect the action, evidence availability, reasons, integrity and detector version.
  5. Open Quillmark at http://localhost:3003 to try a fictional account sign-up and credit-spending action. Keep its results scoped to its own site in the console.

Northstar starts in shadow mode: an assessment does not itself stop the submission. Its browser telemetry is off by default. Missing observations are an expected state to inspect, and an automation indication does not establish unwanted intent.

6. Learn the review loop before changing policy.

Use Sites & integration to inspect allowed origins, action names and integration settings. Use Evaluation to inspect customer outcomes, manual review and scripted fixtures in their separate groups. Keep the detector’s assessment, your decision and the later business outcome separate.

For your own integration, begin with the browser and server SDK documentation. Issue a site-scoped key, keep it on your backend, authenticate the action there and preserve your application’s existing validation. The SDKs are workspace packages, not published npm packages. Begin with observation and report an outcome only when you have a basis for it: confirmed unwanted activity, legitimate activity or unresolved. A block or a rule match alone is not an outcome.

7. Run the checks in layers.

Start with the code and database checks. Run database tests only against the configured local lab:

pnpm typecheck
pnpm lint
pnpm format:check
pnpm test
pnpm test:db
pnpm build

pnpm test does not load .env, so database-dependent tests can skip. pnpm test:db covers migration and retention checks with local configuration loaded. Read the skipped-test names as well as the pass count; missing tools and the optional rollback rehearsal can also cause skips.

Install Chromium if needed. Stop the development processes with Ctrl+C before starting the compiled build on the same ports:

pnpm exec playwright install chromium
pnpm start

In a second terminal, with all local services running:

pnpm test:e2e
EVALUATION_DIR=work/evaluation pnpm evaluate
JOURNEY_DIR=work/journey pnpm demo:journey

Browser tests exercise the interface and integration. The evaluation submits controlled scenarios to Northstar; the journey exercises Quillmark’s account flow in bound and submit-only modes. These commands create fictional records. They demonstrate behaviour on scripted traffic and do not measure detection performance on real shoppers. Browser evidence is written under work/evidence; the commands above keep new evaluation and journey reports under work too.

If you are developing the Shopify adapter, also run pnpm test:shopify and follow the repository’s Shopify runbook. Those local checks do not establish live-store coverage. Live permissions, validation activation and test orders need a separately authorised experiment.

8. Prepare a Shopify monitoring evaluation.

  1. Define one question. Bring a concrete store workflow, a description of the unwanted activity and examples you are authorised to share. Agree who can review the results.
  2. Agree the scope. Confirm the observed surface, installation eligibility, permissions, privacy requirements, review date and minimum useful activity with the team. Use the pilot guide to prepare.
  3. Activate only the agreed observation sources. A guided installation follows readiness checks. Keep existing protections in place and begin in monitor mode. Check a normal journey and a consent-limited journey before interpreting gaps.
  4. Review sessions and outcomes. Compare reported activity with the store’s own records. Record absent or delayed evidence, ordinary activity, confirmed unwanted activity and unresolved cases. A checkout-start observation is not a confirmed order or payment attempt.
  5. Make the next decision explicitly. Stop, agree an extension or separately evaluate a supported control. Monitoring does not establish checkout enforcement, and a quiet review period may be inconclusive.

9. Resolve common local setup problems.

To finish, use Ctrl+C in the application terminal, then run pnpm db:local --stop. This stops the owned local database and preserves its data. On your next visit, start the database, apply local migrations after source updates and run pnpm dev.

Continue with the integration reference, bot-detection guides or Blokk articles.