open-historia
An open source alternative to Pax Historia
Automatically checked · GitHub checked 2026-11-13

Overview
License & Copyright
Copyright (C) 2026 Open Historia
This project is licensed under the terms of the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE file for details.
Contributions are accepted under the Contributor Copyright Assignment Agreement, which assigns the copyright in contributions to the Open Historia Organisation. CLA Assistant asks you to sign it on your first pull request; see CONTRIBUTING.md.
Scenarios Are Released Under CC BY 4.0
The licence above covers the game's code. Scenarios are different: every scenario made in Open Historia that is posted or shared in any way is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0). The same goes for changes suggested to a scenario on the Scenario Hub.
The game says so on the screens a scenario leaves it from, and writes it into every exported file (LICENSE.txt in a .zip, a license record in the scenario's JSON). It does not cover material that was never the poster's to license, or a detailed map or a music track a scenario only names, each of which keeps the licence on its own post.
Music
The game's music is by Scott Buckley (www.scottbuckley.com.au): "Passage Of Time", "Clear Skies", "Frankincense and Myrrh", "Discovery", "Honour Among Thieves", "A Kind Of Hope", "Legionnaire (2022 Remaster)" and "Vanguard", all released under CC BY 4.0. The files are in public/audio, re-encoded at a lower bitrate to make the game smaller and otherwise unchanged (all but "A Kind Of Hope", which is the composer's own file), with their credits beside them; that licence, not the game's, covers them.
Privacy
What the game keeps on your device, what it sends and to whom, and what the project holds: see the privacy policy (source: public/privacy/index.html).
Open Historia
Open Historia is an independent, open-source project and is not affiliated with, endorsed, sponsored, approved, or authorized by Pax Historia. Pax Historia has no involvement in the development, operation, or distribution of Open Historia. Pax Historia™ and all associated trademarks, trade names, and logos are the exclusive property of Pax Historia.

✨ Features
- interactive world map: watch territory, borders, and nations shift as history unfolds
- ai-generated events: dynamic events shaped by your decisions and the state of the world
- diplomacy: negotiate with AI-controlled nations through natural language chat — click any country to talk to it or get an AI intelligence briefing
- ai advisor: consult your advisor for strategic guidance, economic analysis, and situation summaries
- map editor: a full vector map editor (draw, split, merge, paint owners, cities) built into the scenario editor — build a world and hit Apply & Play
- troops: deploy, move and battle armies; deployments stay pending until the AI resolves them; scenarios control which troop types exist in their era
- scenario hub: browse, vote on and import community scenarios from the in-game Community tab, and publish your own
- self-hostable: run your own instance with your own AI backend completely offline
🚀 Play
In your browser
openhistoria.com — nothing to install. Games are saved in your browser, and you bring your own AI key (it goes straight to your provider, never to us). The world map is part of the site.
Local AI (Ollama, LM Studio) needs one extra step in the browser: the server has to allow
the site's origin, e.g. start Ollama with OLLAMA_ORIGINS=https://openhistoria.com. The
desktop app below needs no such setup.
Desktop (offline, single-player)
Download the installer for your platform from the Open Historia for Desktop release, then:
- Windows: run
Open-Historia-Setup.exe, then open Open Historia from the Start Menu - macOS: unzip and drag Open Historia to Applications (first run: macOS closes it once as unsigned; choose Done, then System Settings -> Privacy & Security -> Open Anyway; on macOS 14 and earlier, right-click -> Open)
- Linux:
chmod +x Open-Historia-x86_64.AppImageand run it
The app comes ready to run; the world map downloads the first time it opens. On Windows and Linux it offers new versions itself. On macOS, or to update by hand, install the newest download from the same release over the top: your saves, scenarios and map data are kept.
Code signing policy
Windows builds of Open Historia are code-signed through SignPath Foundation. Free code signing provided by SignPath.io, certificate by SignPath Foundation. A release whose Windows build was signed says so on its release page.
- What is signed: the Windows installer, the app's program and its system speech program, built from the source in this repository. Electron's own runtime libraries are left as Electron ships them.
- Where signed builds come from: only this repository's release workflows (desktop-installer.yml, desktop-beta.yml) on GitHub-hosted runners. Nothing built anywhere else is signed.
- Team roles: committers and reviewers: Arkniem (owner), who reviews every outside contribution before it is merged. Approvers: Arkniem, who approves each signing request by hand.
- Privacy: what the app sends, and to whom (the player's own AI provider, the community hub, update checks, the map download), is set out in the privacy policy.
- Other systems: the macOS app is not signed (see above). The Android app is signed with the project's own release key.
Android app
Download open-historia.apk from the
Android release
and open it to install (allow installs from your browser when Android asks).
Everything is on the phone: your saves and scenarios, the scenario workshop and
the world map — it plays in airplane mode from the first launch. The community
hub and your own AI provider are the only things that use the network. A model
running on your own network (Ollama, LM Studio) works too, with no CORS setup.
Build the APK yourself (needs the Android SDK)
npm run build:android # the app's bundle → dist-android/
cd mobile
npm install
npm run map # fetches + verifies the map data into map-cache/
npm run www # stages the bundle and the map into www/
npx cap sync android
cd android && ./gradlew assembleDebug # gradlew.bat on Windows
The APK lands in mobile/android/app/build/outputs/apk/debug/. (Or open
mobile/android in Android Studio and press Run.) Maintainers: the
Build Android APK action in the Actions tab builds and republishes the
release APK — run it after changing mobile/ or the client. See
docs/mobile.md.
Manual
Prerequisites: Git and Node.js 22 LTS or newer (minimum 20.19 / 22.12 — the client build runs on Vite 7, which requires it). Building the desktop app needs 22.12+, which is what Electron 44 requires; the server and the web client still run on 20.19.
git clone https://github.com/Open-Historia/open-historia.git
cd open-historia
node scripts/fetch-map-assets.mjs # Download the world map data (see note below)
npm install # Install dependencies (includes OpenLayers etc. for the editor)
npm run build # Build the client
node server/server.js # Start the server
Then open http://localhost:3000 in your browser.
Reaching the server from another device
Out of the box the server answers only the machine it runs on — which covers the desktop app, Termux on the same phone, and a browser on the same computer.
To play from your phone or another computer, turn on Settings → Advanced → Network → "Let other devices connect". It takes effect immediately (no restart), it is remembered for next time, and it shows you the exact address to type into the Android app, so you never have to go and find your own IP:
Type this into the Android app:
http://192.168.1.20:3000
Worth knowing before you do: the game's API has no password. While sharing is on, anyone who can reach that address can read, change and delete your games and scenarios — the server can't tell them apart from you. That's fine on a home network you control and a bad idea on café, hotel, dorm or office Wi-Fi. The switch is off by default for that reason, not because sharing is discouraged.
Running headless — Termux, a NAS, a box with no screen to click a toggle on? Set
OH_HOST. It overrides the setting and makes the in-game switch read-only, so a
script and a player can't disagree about who can reach the server:
OH_HOST=0.0.0.0 node server/server.js # every interface
OH_HOST=192.168.1.20 node server/server.js # one interface only
| Variable | Default | What it does |
|---|---|---|
OH_HOST | unset | Which interface to listen on. Overrides the Settings toggle and locks it. Anything but loopback puts the API on your network. |
OH_ALLOW_REMOTE_RELAY | off | Lets other devices use this server's AI relay. Off means the relay only answers this machine, so it can't be used as a proxy by anyone else on the network. The same switch is in Settings → Advanced → Network ("Let other devices send AI calls through this server", shown while sharing is on); this variable overrides it and locks it. |
OH_RATE_LIMIT | 1200 | Requests per minute per network client (loopback is exempt). |
[!TIP] Running the server only — Termux/Android, a headless box, a NAS? Skip the desktop-app tooling:
npm install --omit=dev --omit=optionalThat drops Electron and its build chain (783 packages → 286) while keeping everything the client build and the server actually need. On Android it is the difference between working and not: Electron publishes no Android build, so its install script exits with "Electron builds are not available on platform: android". A plain
npm installstill succeeds there — Electron is anoptionalDependency, so npm reports the failure and carries on — but there is no reason to download it in the first place.
Note: the large map binaries (
*.pmtiles,public/assets/*-seed.*, and the stock worldserver/data/stock/regions.geojson) are not in the repo — they are hosted as GitHub Release assets and downloaded byscripts/fetch-map-assets.mjs. Run it once after cloning (node scripts/fetch-map-assets.mjs); the desktop app runs it for you on first launch — no Git LFS needed. The website and the Android app carry their own web-sized set, which their builds download themselves (scripts/stage-map-assets.mjs).
🌍 Scenarios
Modern Day is the only built-in scenario. All other official presets — World War II — 1939, Medieval — 1200 AD, Rome — 117 AD, Mongol World — 1300 AD, New World — 1650, and Bronze Age — 1200 BC — live on the Scenario Hub, pinned at the top of the in-game Community tab. Import any of them with one click, or publish your own.
To rebuild an official preset from source (specs live in scripts/presets/):
node scripts/presets/build-preset.mjs scripts/presets/wwii-1939.spec.mjs
The built-in Modern Day map is authored in the Scenario Workshop and lives in the repo as
server/seed/default/regions.geojson (with its cities, world and colours beside it); the server
copies that seed into its data directory on first run and whenever the seed's builtInMap changes.
node scripts/build-default-map.mjs regenerates the stock GADM world instead — the map every
scenario without one of its own (the hub presets) renders on.
🗺️ Map editor
Open any scenario's editor and click 🗺️ Open Map Editor (or visit
http://localhost:3000/?editor=1 for the standalone editor). Draw regions, split and
merge borders freehand, paint owners, import 70k cities, sign your map, then
Apply & Play.
🖥️ Host the game yourself
Every build has its own copy of the map: the website and the Android app carry it, and the
desktop app downloads it from the
map-data release
the first time it opens. To host the game yourself, see WEB-DEPLOY.md for
the website, or the manual install above for a local server.