Local setup

ArchGuard runs locally for the enterprise pilot. You need Node.js 22 or later, npm, and Docker Desktop (or any Docker engine with Compose).

1. Start the infrastructure

From the archguard folder:

docker compose up -d

This starts PostgreSQL 16 (port 5432), Redis 7 (port 6379) and a local mock OIDC identity provider (port 8090). The mock provider is for development sign-in only.

2. Configure the environment

cp .env.example .env

Fill in the required values:

Variable Purpose
TOKEN_ENCRYPTION_KEY 32 random bytes, base64. Encrypts Bitbucket tokens and webhook secrets.
AUTH_SECRET Random string used by Auth.js to sign session cookies.
AUTH_OIDC_ISSUER, AUTH_OIDC_CLIENT_ID, AUTH_OIDC_CLIENT_SECRET Your identity provider.
AUTH_ROLE_ADMIN_GROUPS, AUTH_ROLE_ARCHITECT_GROUPS, AUTH_ROLE_VIEWER_GROUPS IdP group names that map to each role.
WEBHOOK_PUBLIC_URL A URL that Bitbucket can reach. See below.
LLM_PROVIDER, LLM_MODEL and the provider settings Your approved language model endpoint.

Generate a key with:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

3. Create the database and the first organization

npm install
npm run db:migrate
npm run db:seed -- pilot "My Company"

db:migrate runs as the database owner and creates the tables, the row-level security policies and the restricted archguard_app role the application uses. db:seed creates the organization (the app itself cannot) and adds the five starter guardrails. The slug (pilot) must match AUTH_DEFAULT_ORG_SLUG.

4. Run the app and the worker

Use two terminals:

npm run dev      # web app on http://localhost:3000
npm run worker   # processes pull request evaluations

Check http://localhost:3000/api/health. It reports db and redis as up when both are reachable.

Letting Bitbucket reach your machine

Bitbucket Cloud must be able to call WEBHOOK_PUBLIC_URL. On a laptop, expose port 3000 with a tunnel approved by your company and set WEBHOOK_PUBLIC_URL to the tunnel address. Repositories enabled before you change the URL need to be disabled and enabled again, so the webhook is registered with the new address.

Using the mock sign-in

With the mock provider, the sign-in page lets you type the claims of the token. Provide an email and a groups array such as ["archguard-admins"]. Without a matching group, sign-in is refused. See Roles and permissions.

Running the tests

npm test
npm run typecheck
npm run docs:check

The tests use an in-process PostgreSQL (PGlite) with the real migrations and the restricted role, so they do not need Docker.