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.
Ports
| App | Address | Repository |
|---|---|---|
| Identity Worker | http://localhost:28500 | buungroup-app |
| Account portal | http://localhost:28501 | buungroup-app |
| MCP gateway | http://localhost:28502 | buungroup-gateway |
| Staff console | http://localhost:28503 | buungroup-staff |
| These docs | http://localhost:28504 | buungroup-app |
| Status page | http://localhost:28505 | buungroup-app |
| Plotwork MCP server | http://localhost:3102/mcp-oauth | plotwork-app, apps/mcp |
| Flung MCP server, and its API | http://localhost:3020/mcp-oauth, http://localhost:3010 | flung-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
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
| Command | What it does |
|---|---|
pnpm dev | Frees the dev ports, then runs the issuer, portal, gateway, staff console and status page together |
pnpm dev:core | The issuer and the portal only |
pnpm --filter @buun-group/developers dev | These docs |
pnpm check | Type check and every test |
pnpm kill:ports | Stops whatever holds a dev port |
pnpm demo | The 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:
- Start the issuer:
pnpm dev:identity. - Run
pnpm dev:exchangeonce. Through the issuer's/admin, it addshttp://localhost:28502as 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. pnpm devfor everything else.- In the staff console at
http://localhost:28503, give yourself a Plotwork or Flung plan under People. - Run the product's MCP server with its issuer
http://localhost:28500and its resource its own local endpoint. - Connect an agent:
claude mcp add --transport http buun-local http://localhost:28502/mcp, and sign in when it asks. - Approve the product's tools under Gateway tools in the console, then list and call them.
| Something is wrong | Look at |
|---|---|
| No product tools listed | The gateway's log, gateway.exchange_refused with the status the issuer answered |
| The issuer refused the trade | The issuer's log, oauth.exchange_refused and its reason: client, subject, account, grant or plan |
plan | Give yourself a plan for that product in the console |
grant | The agent was disconnected in the portal. Connect it again |
| The product answers 401 | Its issuer or its own resource address is not the local one |