Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/at6132/econ/llms.txt

Use this file to discover all available pages before exploring further.

The Realm development stack is two processes: a Python FastAPI engine on port 8000 and a Next.js web client on port 3000. The web client proxies requests at /api/engine to the engine, so you only need one browser tab. Everything runs in-memory by default; you can persist to SQLite with a single API call.

​
Prerequisites

Before you start, make sure you have:
  • Python 3.10+ — the engine’s pyproject.toml requires >=3.10; Python 3.11+ is recommended
  • Node.js 18+ — required for the Next.js web client
  • git — to clone the repository

​
Setup

1

Clone the repository

git clone https://github.com/at6132/econ.git
cd econ
2

Install the engine

Install the realm-engine package in editable mode. This pulls in FastAPI and uvicorn.
cd engine
pip install -e .
To also enable LLM agents (Tier 3) or Lua eval, install optional extras:
# LLM agents (requires ANTHROPIC_API_KEY)
pip install -e ".[llm]"

# Lua eval (requires lupa)
pip install -e ".[lua]"

# All development tools
pip install -e ".[dev]"
3

Start the engine

Run uvicorn from the engine/ directory. The --reload flag restarts the server automatically when you edit Python files.
uvicorn realm.api:app --reload --port 8000
You should see Application startup complete. The engine is now available at http://localhost:8000.
4

Install web dependencies

In a second terminal, install the Next.js project dependencies:
cd web
npm install
5

Start the web client

npm run dev
Next.js starts on port 3000. The dev server watches for file changes automatically.
6

Open the app

Go to http://localhost:3000 in your browser. You should see the Realm map. From here you can claim a plot, survey it, pick a production recipe, and advance ticks to watch inventory update.

​
Running both terminals at once

cd engine
pip install -e .
uvicorn realm.api:app --reload --port 8000
On Windows, there are start-dev.ps1 and start-dev.cmd scripts in the repo root that launch both terminals automatically. Run .\start-dev.ps1 from a PowerShell prompt at the repo root. The script detects a engine/.venv if present, installs dependencies if missing, and opens two new PowerShell windows — one for the API and one for the web client.

​
Resetting the world

During development you can reset the in-memory world to any named scenario without restarting the server. The POST /dev/reset endpoint destroys the current world and bootstraps a fresh one. 
curl -X POST "http://localhost:8000/dev/reset?scenario=frontier&seed=42"
Available scenarios:
A 48×36 grid. You start with $10,000 and a small starter inventory (timber, coal, electricity, iron ore, copper ore, clay, grain). Several Tier 1 NPC vendors and buyers seed the first markets. The standard starting scenario for testing the core economic loop.
Same grid and starter as frontier, but the grain market is disrupted: the normal vendor listing is split between the incumbent vendor at near-market price and a cartel_grain_cell holding stock at a premium. Tests price manipulation and market intelligence dynamics.
A smaller 32×24 grid. You start with only $4,850 — tight capital forces careful resource allocation. Good for testing early-game constraint paths.
A 40×30 grid with $20,500 starting capital. More cash than the frontier scenario but on a medium map. Good for testing market positioning and order-book strategies.
A 42×28 grid with $9,750 starting capital. A near-frontier starting position with a slightly different map shape.
A 48×36 grid (same as frontier) with $10,800 starting capital. Market intel is pre-activated for the first 280 ticks — GET /world returns full market_history from the start. Good for testing analytics and charting flows.
A large 96×72 grid with 50 algorithmic settlers and two population hubs (pop_hub_e, pop_hub_w) each seeded with $50,000 for aggregate demand. Terrain-correlated subsurface (stronger ore under mountains, clay in forests and plains). The genesis_exchange seeds cold-start liquidity in grain, timber, coal, and electricity. Intended for testing large-world dynamics and the full settlement economy.

​
Saving and loading

The engine holds world state in memory. To persist it to disk, call the save endpoint: 
# Save to the default path: saves/realm_dev.sqlite
curl -X POST http://localhost:8000/persistence/save

# Save to a named file
curl -X POST "http://localhost:8000/persistence/save?path=saves/my_run.sqlite"
To restore a save (this replaces the current in-memory world): 
# Load from the default path
curl -X POST http://localhost:8000/persistence/load

# Load from a named file
curl -X POST "http://localhost:8000/persistence/load?path=saves/my_run.sqlite"
The default save path is saves/realm_dev.sqlite at the repo root. The saves/ directory is created automatically if it does not exist. Save files are self-contained SQLite databases — you can copy, rename, or share them freely.

​
Verifying the engine

To confirm the engine is running correctly, hit the health endpoint: 
curl http://localhost:8000/health
# {"status":"ok"}
The interactive API docs are available at http://localhost:8000/docs (Swagger UI) and http://localhost:8000/redoc (ReDoc) while the server is running.

​
Optional: LLM agents

Tier 3 LLM-driven agents (named characters with memory) require an Anthropic API key: 
export ANTHROPIC_API_KEY=sk-ant-...
pip install -e ".[llm]"
uvicorn realm.api:app --reload --port 8000
Check agent status with GET /llm/status and trigger a planning step with POST /llm/step?party=<agent_party_id>. The engine tracks session spend in micro-dollars and enforces a configurable cap to prevent runaway costs. For more on each endpoint see the Engine API Reference. For architecture details, see Technical Architecture.

Build docs developers (and LLMs) love

Get started for freeTalk to us