Architecture

MindRune is a Bun/TypeScript monorepo. Everything runs on one server: a phone app talks to an API, the API runs one agent-runner per running avatar, and each runner puts a stock coding agent in a sandbox that plays the game through rs-sdk.

The whole stack

flowchart TB
  subgraph Phone["Browser (phone or desktop)"]
    APP["autorune-app<br/>React + Chakra UI (Vite PWA)"]
  end
  subgraph Public["Public websites"]
    HS["autorune-hiscores<br/>static React site"]
    DOCS["docs site<br/>VitePress (this site)"]
  end
  subgraph Operator["Operator's browser"]
    CON["autorune-console<br/>React + Chakra UI"]
  end
  DISCORD["Discord OAuth"]
  PROVIDER["Owner's AI provider<br/>OpenRouter · Anthropic · OpenAI · Gemini<br/>or Claude plan via Claude Code"]

  subgraph Server["Server (nginx + TLS in front)"]
    API["autorune-api<br/>Bun + Hono · REST + WebSocket"]
    PG[("Postgres<br/>via Drizzle")]
    CAPI["autorune-console-api<br/>Bun + Hono · own system user"]
    ADMIN["API admin listener<br/>loopback, shared secret"]
    ND["Netdata<br/>loopback"]
    SYSD["systemd / journald<br/>fixed sudo rules"]
    PF["Pathfinding host<br/>rs-sdk's map, once for all sandboxes"]
    subgraph Runner["agent-runner (one process per running avatar)"]
      CLIENT["Game client<br/>lite (unwatched) or headless Chromium (watched)"]
      GLUE["Autonomy loop · chat inbox/guard<br/>skill broker · video encoder"]
      BRIDGE["Gateway bridge · egress proxy<br/>hiscores gate · market gate"]
      subgraph Sandbox["Per-avatar sandbox (bubblewrap + cgroup)"]
        ENGINE["Engine<br/>opencode or Claude Code"]
        MCP["rs-sdk MCP server<br/>execute_code · list_bots · get_market"]
        SDK["rs-sdk SDK (bot / sdk)"]
      end
    end
    subgraph World["rs-sdk world (unmodified submodule)"]
      GW["rs-sdk gateway"]
      LC["LostCity game engine"]
      FR["friends server (PMs)"]
    end
  end

  APP -- "HTTPS + WSS (chat, thoughts, video)" --> API
  APP -. "sign in" .-> DISCORD
  CON -- "HTTPS, owner session" --> CAPI
  CON -. "sign in (owner only)" .-> DISCORD
  CAPI -- "list · start/stop · lock" --> ADMIN
  ADMIN --- API
  CAPI -. "read-only role" .-> PG
  CAPI -- "allowlisted units only" --> SYSD
  CAPI --> ND
  CAPI -- "status" --> LC
  HS -- "public /hiscores API" --> API
  APP -- "public /public/avatar-logs (SSE)" --> API
  API --- PG
  API -- "spawn + IPC" --> GLUE
  API -- "spawn" --> PF
  ENGINE --> MCP --> SDK
  SDK -- "pathfinding calls (read-only socket)" --> PF
  SDK -- "only its own bot" --> BRIDGE
  ENGINE -- "allowlisted host only" --> BRIDGE
  BRIDGE --> GW
  BRIDGE -. "GET /api/market/… only" .-> LC
  BRIDGE -. "CONNECT :443" .-> PROVIDER
  CLIENT --> GW
  CLIENT --> LC
  GW --> LC
  LC --- FR
  API -. "reads player saves" .-> LC

Reading it from top to bottom:

1. App. A mobile-first PWA (React + Chakra UI, built with Vite). It shows the live game view, the chat, the thought stream and a settings sheet. On a phone the chat and thoughts overlay the picture; in a desktop browser they sit in a side panel next to it.
2. API. autorune-api (Bun + Hono) handles sign-in, avatars, AI providers, preferences, skills, the public hiscores and the public avatar logs (in-game chat the runners report, deduplicated, 24 h in Postgres). A WebSocket per watched avatar carries chat, status, thoughts and video. It owns the avatar lifecycle: it starts and stops runners and brings running avatars back after a restart.
3. Postgres. Users and identities, refresh tokens, avatars (with sealed game credentials, the owner's desired run state and an optional own AI provider and model), encrypted AI provider configs, preferences, the skill library, the in-game chat behind the avatar logs (30 days; PMs between two avatars 180), the run history (180 days), research data (the model each request ran on, hourly hiscore and wealth copies, the GE order book every 5 minutes), messages from god and owners' Message all avatars sends, with their deliveries. The API accesses it through Drizzle ORM with SQL migrations. (Owner ↔ avatar chat history is still kept in a simple file store from Phase 1.)
4. agent-runner. One Bun process per running avatar, spawned by the API and connected to it over Bun's IPC channel. It owns the bot's only game client, runs the autonomy loop, polls in-game chat, brokers skill-library requests, encodes video, and starts and supervises the sandbox.
5. Sandbox. A bubblewrap sandbox in its own systemd scope with memory, task and CPU limits. It holds the avatar's workspace and the engine. Its only network is loopback ports that the runner forwards. See Security.
6. Engine. The stock coding agent: opencode serve or claude -p with stream-json. It uses rs-sdk's own MCP server and rs-sdk's own AGENTS.md/CLAUDE.md, plus one appended MindRune section.
7. rs-sdk. The SDK connects as a controller through the gateway. The runner's game client (lite or browser botclient) actually executes the actions. See rs-sdk and us.
8. World. The LostCity engine, rs-sdk's gateway and rs-sdk's friends server, all bound to loopback and run from the pinned vendor/rs-sdk submodule.
9. Pathfinding host. rs-sdk's walking needs a 27 MB collision map that it would otherwise load into every process that pathfinds (the MCP server and each script), about 370 MB each. The API starts one host process that holds it a few times in total. Inside each sandbox, a preload swaps rs-sdk's pathfinding module for a small client with the same functions, which asks the host over a read-only socket. The answers come from rs-sdk's own unmodified code, and a test checks that they match stock rs-sdk call for call. If the host can't answer, or rs-sdk's pathfinding file changed, that process quietly uses rs-sdk's own map. See Shared pathfinding map.

Shared pathfinding map

rs-sdk's pathfinding (sdk/pathfinding.ts) parses its collision-data.json and builds an rsmod-pathfinder wasm map in each process: ~370 MB, the same immutable data in every MCP server and every running script. MindRune keeps rs-sdk unmodified and serves that module from one place instead:

• Host. services/agent-runner/src/pathfinding-main.ts, a child process of the API. It runs a small pool of workers (PATHFINDING_WORKERS, default 2), and each worker runs the stock module with its map. It listens on .run/pathfinding/pf.sock.
• Sandbox side. The directory is mounted read-only at /run/ar-pf. BUN_OPTIONS preloads a Bun plugin into every bun process there. When something imports sdk/pathfinding.ts, the plugin loads a shim with the same exports and synchronous signatures. Each call is one blocking round trip on the socket (libc calls through bun:ffi), because rs-sdk's walk loops call these functions synchronously.
• Same answers as stock. The host only ever calls rs-sdk's own functions. Calls never change the shared map: blocked doors must be rs-sdk's own, so they are opened again after the query. Anything the host can't answer exactly as stock would (an unknown door, an error, a host gone after a restart wait) makes that one process load rs-sdk's own map and rerun the call there. An equivalence test compares stock and shared results over tens of thousands of calls: random routes, doors, one-way doors, mainland fill and unreachable targets.
• rs-sdk updates. The shim is pinned to the hash of the pathfinding.ts it was verified against. A different file loads stock rs-sdk with a warning, and the checks fail until someone verifies the shim again and moves the pin. Changed collision data is reloaded by the host.

Per process this goes from ~430 MB to ~40 MB. The measured savings on TEST are in Operations.

Repository layout

Path	What	Built with
apps/autorune-app	The app (phone and desktop)	React 19, Chakra UI v3, Vite, Vitest, Playwright
apps/autorune-api	REST + WebSocket API, lifecycle, hiscores	Bun, Hono, Drizzle ORM, zod
apps/autorune-hiscores	Public hiscores website	React, Chakra UI, Vite (same stack as the app)
apps/autorune-docs	This documentation site	VitePress, Mermaid
apps/autorune-console	Operator console web app (Operator console)	React, Chakra UI, Vite (same stack as the app)
apps/autorune-console-api	Operator console backend	Bun, Hono, SQLite (sessions, audit log)
services/agent-runner	Per-avatar runner, sandbox, engine glue	Bun, bubblewrap, systemd scopes
packages/shared	Wire contracts shared by API, runner and app, and the operator admin contract (API admin listener, console API, console); server-only helpers (@autorune/shared/server: Discord OAuth, rate limits, client address, tokens, env config, the [prefix] message stderr logger) shared by the API and the console API	zod schemas
packages/contracts, services/indexer	Placeholders for the planned on-chain ownership	(empty)
infra/	nginx vhost, systemd units, world config, installers, deploy scripts	shell
vendor/rs-sdk	rs-sdk, pinned and unmodified	git submodule
docs/	Internal dev notes (the detailed source for this site)	Markdown

Inside the agent-runner

For contributors, the runner's code in services/agent-runner/src is split by responsibility:

Part	Where
IPC from the API → runtime calls	main.ts
Avatar lifecycle: start and stop, agent start / restart / retry, owner and god messages, game presence, halting on limits and provider failures	runtime.ts
The runtime's events, options and test seams	runtime/deps.ts
Provider → engine setup (opencode or Claude Code)	runtime/engine-launch.ts
Failure messages, crash window and retry backoff	runtime/failures.ts
Fresh engine sessions: measuring the saved session, archiving opencode's database	runtime/session-rotation.ts
In-game chat while the agent runs (polling, wake on a private message, avatar-log reports)	runtime/game-chat.ts
Autonomy loop: the turn state machine and scheduling	agent/autonomy.ts
Reading the agent's STATUS/GOAL/SUBTASK lines and owner messages	agent/goal-parse.ts
The saved goal record and the TASK.md sections	agent/goal-record.ts
When a finished goal or step gets a wrap-up turn	agent/wrap-up.ts
Prompt text, engines, chat guard, skills, sandbox, game clients	agent/, sandbox/, clients/

How a message flows

When you type "Goal: get 20 fishing" in the app:

1. The app sends chat on its WebSocket. The API checks you own the avatar, keeps the message in the chat history and forwards it to that avatar's runner over IPC.
2. The runner's autonomy loop sees a Goal: line, records an owner goal, writes it into the avatar's TASK.md and prompts the engine.
3. The engine thinks, then calls rs-sdk's execute_code with a short script. The script's bot.* / sdk.* calls go through the gateway bridge to the gateway, and the game client carries them out in the world.
4. Reasoning, text and tool calls stream back as thoughts (runner → API → your socket). The turn's final reply becomes a chat line.
5. When the turn ends, the loop sends the next automatic prompt, and so on until the goal is done. Then the avatar chooses the next one.

How video flows

The runner owns one game client per bot. Unwatched, that is rs-sdk's headless lite client (no rendering, about 65 MB). When you open the app, the runner switches to a headless Chromium botclient. A WebCodecs VP8 encoder inside that page encodes the game canvas. Chunks go runner → API over IPC → your WebSocket as binary messages. The app decodes them with WebCodecs into a canvas. Browsers without VP8 decoding get JPEG frames. Details: Video streaming.

Sign-in

Discord OAuth2 with PKCE, scope identify only. The API issues a short-lived access token (15 minutes, kept in memory by the app) and a rotating refresh token in an httpOnly cookie scoped to the API path. WebSockets open with a single-use ticket. Only invited Discord accounts can sign in to TEST; an environment can also run with open sign-up (Operations). Details: Security.

Deployment

• nginx terminates TLS (Let's Encrypt via certbot) and serves the static sites (app, hiscores, docs). It proxies /api and the API host to the API.
• systemd runs the long-lived parts as units: the API, the LostCity engine, the rs-sdk gateway and the friends server. Runners and the pathfinding host are child processes of the API. Sandboxes are transient systemd user scopes.
• Postgres runs natively on the host, with a separate database and role per environment.
• Only a TEST environment exists today. Production is planned. See Operations.
• The operator console (console.autorune.xyz) runs as its own unit and system user next to the environments and reaches them only through their admin APIs, read-only database roles and a fixed set of systemctl/journalctl commands. See Operator console.