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.