Cosmopolitan Governance App (CGA)
⚠️ Early development — experimental and unverified. This is pre-alpha software: not
security-audited, not validated in real-world use, and its data formats can change at any time
with no migration path. Do not use it for real elections, real governance decisions, or real
personal data. It is for evaluation, development, and contribution only — at your own risk,
with no warranty of any kind (see LICENSE).
We endeavor to answer the question: for a given population, what are the optimal methods for
distributing power between all entities, such that the most individuals would agree that the
methods selected are the fairest that can be implemented? — or — how do we get eight billion
people to get along?
The CGA implements A Fair Constitution (Cosmopolitan Template)
as interactive, automatable software: residency, elections, legislatures, executives, judiciaries,
organizations, and nested jurisdictions from neighborhood to planetary scale. It is federated:
anyone can run their own world, standalone or joined into a mesh of instances that mirror and
sync each other's public records.
Get started
Everything runs inside Docker, so you don't install databases or programming languages —
just Docker, then one command. Plan on ~20 GB of free disk and leaving the computer on for the
first run.
Step 1 — install Docker.
- Windows / Mac: install Docker Desktop,
open it, and wait until it says Engine running.
- Linux / Raspberry Pi:
curl -fsSL https://get.docker.com | sh, then
sudo usermod -aG docker $USER and log out and back in.
Step 2 — run the start command for your system. It downloads the app, starts it, and opens
the setup page when it's ready. The first run builds everything — give it 10–30 minutes; later
starts take seconds.
Windows 10 / 11 — open PowerShell (press Start, type PowerShell, press Enter) and paste:
irm https://raw.githubusercontent.com/CosmopolitanCoalition/fair-constitution-app/main/get-started.ps1 | iex
macOS / Linux / Raspberry Pi — open Terminal and paste:
curl -fsSL https://raw.githubusercontent.com/CosmopolitanCoalition/fair-constitution-app/main/get-started.sh | bash
Already downloaded the code yourself (ZIP or git clone)? Run the same script from inside
that folder — .\get-started.ps1 on Windows, ./get-started.sh elsewhere — and it uses your
copy instead of downloading.
Updating: re-run the same start command any time. It pulls the latest code and applies the
update automatically (database migrations, interface build, worker restart). Installs made from
a ZIP are connected to the update channel automatically on their next run — your settings and
data are never touched by an update.
Step 3 — answer the questions in your browser. The app comes up at
http://localhost:8080/setup and the setup wizard carries you the rest of the way:
- Create the world's database and your founder account. The first page detects the empty
database, applies the schema, and makes you this world's operator.
- Start a new world — or join an existing one? Joining replicates an existing game onto
this computer: enter the host's address and approve from there. Starting new continues below.
- Cosmic address — which place this world is for: a neighborhood, a city, a country… up to
the whole planet.
- Constitutional defaults — the rules of the world. Template values are a starting
reference, not locks; the founder can change them.
- Map data — load real geography and population (see Map data below).
- Districts and institutions — district maps are drawn and the civic institutions are
seated. You're in, signed in as the founder, with a live world.
On a server or a cloud machine, open the same page at that machine's address instead of
localhost (for example http://10.0.0.6:8080/setup over your VPN, or your domain once DNS is
set). The interface is a built bundle served on port 8080; no other port is needed.
Didn't open? Make sure Docker Desktop is running, give a first run a few more minutes (it's
still building), then reload the page.
Running it on the internet
The steps above give you a world on your own computer — perfect for trying it out, and for
a home node others on your network can reach. To put a node on the public internet at your
own domain, with HTTPS, chat and voice working, follow
docs/FRESH-NODE-START-CLOUD.md.
It is the same app and the same one command; a rented cloud machine is just a computer you
don't have to keep under a desk. The extra work is only what any public address needs: a
machine, DNS records, and a few open ports. Written against Azure because that is what has
been tested — any provider with a Linux VM and a public IP works identically.
Map data
The world is built from real datasets: geoBoundaries (jurisdiction boundaries) and
WorldPop (population). Download them by following
docs/DATA_ACQUISITION.md.
The start command asks where they are. On the first run, the get-started script asks for
your map-data folder and points the app at it before the containers are built — so it's ready
from the moment the app comes up, with no extra steps. Already have your files at, say,
D:\map-files? Just type that when prompted. Don't have them yet? Leave it blank and download
them later from inside the app. To change the folder afterward, re-run the start script with
-Reconfigure (Windows) / --reconfigure (macOS/Linux) — it re-points the app and restarts it
for you, no Docker commands needed. (You can also preseed it non-interactively by setting
CGA_ARCHIVE_PATH before running.)
A host that resizes (cloud boxes). Every service returns at boot through Docker's restart
policy. A container keeps the memory caps it was created with, so after a resize the sizes must be
re-derived and the services recreated. On Linux with systemd, install the boot check once:
./get-started.sh --install-boot-unit. At every boot it runs ./get-started.sh --boot: when the
host's RAM or cores changed it re-derives every value in the DERIVED_KEYS ledger, recreates the
services that are running, re-bakes the config cache and restarts Horizon. On an unchanged host it
does nothing. It never updates the code. A box that takes code only on the desk's word sets
CGA_NO_PULL=1 in .env; --rederive and --boot never pull in any case.
Inside the app, the Map data step shows what it detected, lets you scope the import to a
single country for a fast first world, or download the datasets over the internet country by
country. The full planet is ~14 GB of source data and a 6–12 hour import.
Languages
The app runs in 76 languages: English, the six UN languages, Polish, Italian, Turkish, and every
language on the Cosmopolitan Coalition website's translation programme. Every string of the
interface and every server message exists in all of them, and all are switched on.
Read this before you trust a screen in another language. English is the source. Every other
language is a machine draft: produced by an open model under a constitutional glossary,
checked automatically for intact placeholders, tokens and citations, and then read in samples by a
reviewer model that graded each language. No human has yet read most languages end to end.
- Translation status — the table: one row per language with
its coverage, its reading-review grade, and whether a native reader has signed off.
- Methods — how the text was made translatable, how the drafts were
produced and gated, how the samples were read, and what the accessibility sweep checks.
If you read one of these languages, you can fix it. Sign in, add the language to your record,
and open the translation board at /system/translations: it queues the drafts for your language,
and each string you confirm or correct is recorded. The languages graded C in the status table
are the ones that need a reader first.
Video library
Every screen's Learning Drawer can open a short film, narrated and captioned in 77 languages
from one silent master: the Cosmopolitan Coalition website's 61 films, played by the same
multi-track player the website uses. The app ships the catalog, not the media (54.8 GB at the
website's quality: 17 GB of video, 38 GB of audio, 72 MB of captions).
Getting the films onto a box. Inside the app, the Map data step has a Video library
panel. It downloads the films from the public website into your local library, resumes after a
stop, and can be halted and resumed. It pulls all 61 films by default, or the ones you pick. The
same panel points the app at a folder you already have: set the library folder (MEDIA_DIR), then
re-run the start script so the containers pick it up. MEDIA_DIR is the Subjects folder
itself, laid out as <Subject>/<Subject>-Silent.mp4, <Subject>/audio/<Subject>-<Language>.m4a
and <Subject>/captions/<Subject>-<Language>.vtt, the website's own layout. A folder that
already holds that layout plays with no copy at all.
From a shell, the same engine is php artisan media:pull (website download, queued), --sync
for a box without a queue worker, --source=folder --from=/media-source to copy from a local
folder mounted through MEDIA_SOURCE_DIR, --status and --halt. Only the website-quality
files are copied; smaller variants in a source folder are ignored.
Adding or replacing a film. /videos/manage uploads a silent master, its audio tracks and
its caption tracks (the language is read from the -<Language> filename suffix, or chosen per
file), and assigns any film to any screen's Learning Drawer. Reading the page is open to
everyone; uploading and assigning is an operator tool during development. The library itself is
at /videos.
Advanced
For people running servers or contributing code — none of this is needed for a normal install:
- Scripted / shareable deploys —
deploy.sh (Linux · macOS) /
deploy.ps1 (Windows, PowerShell 7): headless one-command node deploy, with
flags for custom ports, second instances on one machine, and joining as a mirror in one step.
./deploy.sh --help lists everything.
- Joining across machines — the operator runbook for a UI-driven join over your network:
docs/operator/multibox-ui-run.md. One
.env value
(FEDERATION_SELF_URL) must be set before bring-up so peers can reach you back.
- The survival mesh — redundant secure transports between instances (private tailnet, Tor,
Yggdrasil): bootstrap/README.md.
- Developing the interface — a normal install serves a built bundle and never runs the
Vite dev server. Developers set
COMPOSE_PROFILES=dev (plus APP_ENV=local,
APP_DEBUG=true) in .env to run the hot-reload dev server on port 5173; on a remote dev
box also set VITE_DEV_ORIGIN=http://<box-address>:5173. Re-run the start script after
changing them.
- Technical and contributor documentation — docs/, including the ETL pipeline
reference at scripts/etl/README.md.
License
Open source — see LICENSE. Constitutional intellectual property is always public
domain per Article III §5 of A Fair Constitution.
