Buun Group Developers
Pages

Local development

How to run Buun Identity, the portal, the gateway and the staff console on one machine, and test a product through the gateway over localhost.

Markdown

Ports

AppAddressRepository
Identity Workerhttp://localhost:28500buungroup-app
Account portalhttp://localhost:28501buungroup-app
MCP gatewayhttp://localhost:28502buungroup-gateway
Staff consolehttp://localhost:28503buungroup-staff
These docshttp://localhost:28504buungroup-app
Status pagehttp://localhost:28505buungroup-app
Plotwork MCP serverhttp://localhost:3102/mcp-oauthplotwork-app, apps/mcp
Flung MCP server, and its APIhttp://localhost:3020/mcp-oauth, http://localhost:3010flung-app, apps/mcp and apps/api

The Buun Group ports are fixed in tools/dev-ports.json of buungroup-app, all in 285xx, so every product can run at once. A port that is taken stops the app instead of moving it.

First time

sh
git clone --recurse-submodules git@github.com:buun-group/buungroup-app.git
cd buungroup-app
NODE_AUTH_TOKEN=$(gh auth token) pnpm install
cp apps/identity/.dev.vars.example apps/identity/.dev.vars          # fill in each value as its comment says
cp repositories/buungroup-gateway/.dev.vars.example repositories/buungroup-gateway/.dev.vars
cp repositories/buungroup-staff/.dev.vars.example repositories/buungroup-staff/.dev.vars

Without a mail key, a sign-in code is written to the Worker's log as auth.code.dev, and a staff code as staff.code.dev.

Every day

CommandWhat it does
pnpm devFrees the dev ports, then runs the issuer, portal, gateway, staff console and status page together
pnpm dev:coreThe issuer and the portal only
pnpm --filter @buun-group/developers devThese docs
pnpm checkType check and every test
pnpm kill:portsStops whatever holds a dev port
pnpm demoThe staff console, the portal and these docs with made-up data, no Worker or database, on ports 28591 to 28593
pnpm demo:shot <app> [path...]Screenshots of a demo app in both themes, such as pnpm demo:shot staff /clients

Testing a product through the gateway

In local development the gateway reaches the products on the same machine, and both Plotwork and Flung are marked as accepting Buun Identity tokens. Once a product's MCP server accepts them:

  1. Start the issuer: pnpm dev:identity.
  2. Run pnpm dev:exchange once. Through the issuer's /admin, it adds http://localhost:28502 as the gateway agents sign in for, adds both products' local MCP servers as resource servers, registers the gateway's exchange client, and writes the client's id and secret into the gateway's .dev.vars. The secret is never printed. Running it again replaces the client.
  3. pnpm dev for everything else.
  4. In the staff console at http://localhost:28503, give yourself a Plotwork or Flung plan under People.
  5. Run the product's MCP server with its issuer http://localhost:28500 and its resource its own local endpoint.
  6. Connect an agent: claude mcp add --transport http buun-local http://localhost:28502/mcp, and sign in when it asks.
  7. Approve the product's tools under Gateway tools in the console, then list and call them.
Something is wrongLook at
No product tools listedThe gateway's log, gateway.exchange_refused with the status the issuer answered
The issuer refused the tradeThe issuer's log, oauth.exchange_refused and its reason: client, subject, account, grant or plan
planGive yourself a plan for that product in the console
grantThe agent was disconnected in the portal. Connect it again
The product answers 401Its issuer or its own resource address is not the local one