Run the app locally
Start the public app, then add only the services your feature needs.
The public app boots against Somnia Shannon using checked-in defaults. You can start it without a database, model credential or operator wallet.
Requirements
- Node.js 22 or later, as required by the application manifest.
- pnpm 11.24.0, the package manager pinned by this checkout.
- The Masayume application repository. This documentation site is a separate repository.
- Foundry only if you are working on the Solidity contracts.
Start the application
From the application repository root:
pnpm install
pnpm devOpen the local address printed by Next. Public market discovery uses the configured testnet indexer, RPC/WebSocket endpoints and price feed, so a working local server still depends on those remote services answering.
Use Status on the deployment you are inspecting to distinguish an unavailable dependency from an empty result.
Workspace map
| Directory | Role |
|---|---|
web | Next app, UI and server routes |
packages/core | Domain rules, maths, game engines and parsers |
packages/markets | Somnia Markets SDK and contract boundary |
packages/brain | Shared AI provider resolver and structured agent reads |
packages/db | Postgres schema and record access |
services/ops | Long-running workers and game room |
contracts | Solidity contracts and Foundry scripts |
scripts | Architecture checks and protocol tools |
Add a capability
| You want | Add |
|---|---|
| Sensei or Studio Dry read | A supported AI model credential on web |
| Comments, Takes or durable histories | DATABASE_URL |
| House agent execution | A separately configured strategy runner |
| Multiplayer duel rooms | Shared room secret, room URL, running ops and deck recovery configuration |
| Trade from X | Web OAuth configuration plus a separately configured mention relay |
| Private mode | A server desk key matching the deployed PrivateDesk role |
See Configuration before adding values. Server private keys must never use a NEXT_PUBLIC_ name.
Check a change
pnpm typecheck
pnpm invariants
pnpm test
pnpm --filter web buildThe invariant checker includes architecture boundaries such as keeping the Somnia SDK behind the market package. Contract checks run separately:
pnpm contracts:testThe application pins Next 16.3.4 in web/package.json. Read the relevant installed guides under web/node_modules/next/dist/docs/ before editing framework-specific code, and check the actual manifest if the dependency has changed. Local AI instructions and research notes are ignored build aids; a fresh checkout does not need them to install or run.
Database setup
The database package uses postgres and plain schema SQL. It creates missing tables on first use under a transaction/advisory lock. There is no separate Drizzle command to run. This mechanism handles creation; future changes to existing rows or columns require a deliberate migration plan.
Do not start the whole ops service merely to browse the app. Configured actors can sign transactions. Use Services and select the process you need.
Source notes
This guide follows the application code reviewed on 2026-09-07. Links point to that reviewed commit and require repository access. GitHub may show 404 if you are signed out or do not have access.