A soap opera generated by your idle GPU. (Or somebody else's — cloud minds are a config entry; no GPU required.)
The observatory, live: the town map with monument plaques, and the transcript where the show actually happens. Five minds, one town, nobody playing.
Pepperton is a small simulated town where every villager is a different local LLM — a mistral, a qwen, a llama, a phi — each with a job, money, needs, a personality, a secret goal, and a phone. They live in a world that enforces physics, remember what happens to them, write diaries at night, react to real news piped in through the diner radio, and post in a town group chat they invented themselves and immediately used for debt collection.
You don't play it. You watch it, like television that runs on your own hardware — a live map with speech bubbles, a scrolling town transcript, and an inspector that shows you any villager's memories and the exact prompt behind their last decision.
Within one day of first boot, real towns have produced: a con man stringing a debtor along with an invented "lead," a folk belief that the park ducks are an intelligence network, hashtag activism, a faction schism, threats, a public pile-on that rewrote one villager's private debt into accepted fact, and the saddest diary entry ever written by a 3.8B-parameter mind. See LORE.md for the full chronicle — every law in this codebase was passed in response to a crime an actual villager committed.
Local network only. The observatory server has no authentication — the API includes controls that pause the sim, inject chaos events, and puppet villagers. That's fine on localhost or a trusted home LAN. Never port-forward it to the internet. If you want to show your town to the world, stream or screenshot it; don't expose the server.
Terrarium by design. Pepperton never touches real platforms, real accounts, or real identities — its only outside contact is reading public RSS headlines. That is a permanent design line, not an oversight: contributions that connect villagers to real social networks, messaging services, or real people will be declined. This is a fish tank. The glass does not open.
Unmoderated output. Villagers are uncensored local models improvising drama. What they say is generated on your machine, by your models, under your roof — expect the occasional line you wouldn't put on a greeting card, and know that it's yours to curate before sharing.
Hobby software. Provided as-is under the MIT license (see LICENSE — no warranty, no liability). Issues and PRs are welcome but may compost peacefully. The maintainer has a town to watch.
Needs: Python 3.10+. For live minds: Ollama with a few small models — or no GPU at all: Ollama's cloud tags and any OpenAI-compatible gateway (OpenRouter, Groq, ...) are one config entry each (see Casts and providers below). Mock mode needs nothing.
pip install -r requirements.txt
python run.py # observatory at http://localhost:8811
python run.py --headless 96 # one sim-day fast, no server (smoke test)
python run.py --seed 7 # pin the cast (random archetypes per seed)
python run.py --live # real Ollama minds (default is mock)
Mock mode (default) runs the whole town on scripted brains — no GPU — so you can see everything work before spending a single token.
One model playing five characters is a puppet show. Five model
families is a town. Mistral schemes and founds things. Qwen
overthinks and gets suspicious. Llama agrees with everyone, sometimes
verbatim (there's a law about it now). Phi sleeps. The friction
between temperaments is where the show comes from — cast in
config.py (MODEL_POOL), spread across multiple GPUs via
OLLAMA_HOSTS if you have them.
The observatory is no longer watch-only.
🎬 Director (header) — roll any chaos event by name or take a random weighted one, and perform a brain transplant: swap which model plays a villager mid-run, memories and money and grudges intact.
Take the seat (click a villager, top of the inspector) — possession
with a UI. Pick a verb, fill in the fields it asks for, and the action
lands on the next tick. All thirteen verbs are there; text → everyone
posts to the town group chat, which is the surest way to be heard, since
untargeted speech only reaches whoever is standing in the room.
Writes are queued and applied between ticks rather than blocking on the engine lock — clicking a button used to wait up to the full model timeout (107s, measured) for the town to stop thinking.
config.py holds named casts — pick one with CAST:
| cast | minds | needs |
|---|---|---|
local |
the five upstream families (mistral, qwen3, qwen2.5, phi4-mini, llama3.2) | a GPU |
cloud |
Ollama-cloud tags (glm, minimax, deepseek, nemotron, gemma) | ollama signin |
mixed |
cloud minds beside small local ones | both |
Each entry is (model_tag, provider_key). A provider is how that mind
is reached, declared in config.PROVIDERS:
"myrouter": {"api": "openai", # or "ollama"
"url": "https://openrouter.ai/api/v1",
"api_key_env": "OPENROUTER_API_KEY"}, # key lives in the envapi: "ollama" speaks /api/chat (local models and :cloud tags alike);
api: "openai" speaks /chat/completions, so any OpenAI-compatible
gateway — OpenRouter, Groq, Together, vLLM, LM Studio — is a config entry,
not a code change. Every OLLAMA_HOSTS key is folded in automatically, so
older configs keep working.
A provider that is unreachable, unpaid, or missing its key does not stop the town: that villager quietly falls back to its mock understudy, and the reason shows up in the observatory's inspector. Check a cast for real before you run on it:
python tests/brains_live.py # the current cast
python tests/brains_live.py mixed # some other cast
python tests/brains_live.py mistral:latest@default # one mindconfig.py every knob: pacing (accelerated <-> realtime), casting,
archetypes, town voice, needs, radio feeds, chaos weights
sim/world.py locations, clock, and the physics that keep models honest
sim/memory.py Stanford-style memory streams (recency+importance+relevance)
sim/brains.py LLMBrain (ollama + openai-compatible providers) /
MockBrain / ExternalBrain (possession seat)
sim/engine.py the tick loop, decision cadence, nightly reflections
sim/radio.py real RSS headlines -> in-world bulletins (info has geography:
only villagers AT the radio hear the news)
sim/director.py the chaos engine: anonymous texts, planted rumors, leaks
to the group chat, duck omens, dead air — and sometimes
a stranger steps off the bus
server/ FastAPI + websocket observatory (map, bubbles, transcript,
click-a-villager inspector with raw prompts/replies)
LORE.md what happened in the first towns, and why each law exists
The anti-boring code, each statute named for its criminal: the Cal Amendment (no infinite free meals), the Repetition Act, Echo Ban, Paraphrase Act, and Soapbox Law (no broken records, no parroting, no speeches to empty rooms), and the Insomnia Clause (no sleeping through your one wild and precious simulated life). Physics rejects the action and tells the model why, which becomes a memory, which changes behavior. Discipline through consequences, not prompt begging.
Money is a closed loop: every dollar is in a pocket, a business till,
or the town fund. Meals fill the diner's till; the till pays the
cook's wages; rent (every 3 sim-days) refills the fund that pays the
public workers. Dry tills issue back-pay IOUs into a public ledger,
and businesses that can't make payroll stop offering shifts. The
First Bank lends against the only credit score this town has —
your build shifts on the notice board — and posts arrears publicly,
because the ledger forgets nothing. Saying "I'll pay you back" out
loud creates a recorded promise: keep it (the pay action) or the
whole town learns what your word is worth. Nobody prints money.
(The Director still can. The Director is not bound by economics.)
ECONOMY = False in config restores the old open-faucet world.
Villagers can text privately (unoverhearable — secrets finally travel)
or post to the town-wide group chat. The group chat exists because a
villager repeatedly tried to text a "town rumor mill" that didn't
exist, so it was built and named after his dream: Pepperton_Gossip.
Users demanded the feature from inside the simulation.
Chaos rolls quietly (~1.3 events/day, configurable): unsigned texts, rumors implanted as memories, found money, radio dead-air, private messages leaked to the group chat, omens at the duck pond, and — rare, weighted, glorious — a stranger with one bag and a hidden agenda who is in nobody's contacts. You also get a god button:
curl -X POST localhost:8811/api/chaos -d '{"event":"stranger"}' -H 'Content-Type: application/json'
Every villager's mind is pluggable. POST /api/possess/{name} lets an
external intelligence — you, a script, a much larger model — quietly
take over any citizen. The town is not told which of its residents are
possessed. Use responsibly, or don't.
PACING_MODE in config: accelerated (a sim-day per ~15 real minutes
of watching, great for active viewing) or realtime (their morning is
your morning; read the transcript with your coffee like a newspaper
from a parallel world).
Persistent crises (storms that stay broken until someone fixes them), rumor mutation across retellings, forked-timeline experiments (the determinism is already there), spectator/broadcast mode (let chat vote on Director events), more archetypes and locations, strangers with deeper cover stories, Rosie.
MIT licensed. Bring your own GPU and your own sickness.