# 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

```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

| 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:

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 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 |

Source: https://developers.buungroup.com/local-development
