-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Reclaim the right to be unreachable.
Sovereign is a self-hosted personal communication router. It sits between you and your digital world — WhatsApp, Instagram, Telegram, email, SMS — evaluates every incoming message, and either delivers it to your dumb phone as a plain SMS or holds it quietly in the Vault until you choose to engage.
No managed cloud. No subscription. No company holding your messages.
This is the knowledge base for everyone running their own Realm. It covers everything from first installation to fine-tuning your Decrees after months of use. It is written in two registers: technical where it needs to be, plain language everywhere else.
If you are brand new, start at the top and read in order. If you are looking for something specific, the index below will get you there.
All day, messages arrive from many places. Sovereign reads each one and asks a single question: does this need to reach me right now? If yes, a short SMS goes to your simple phone — the only time it makes a sound. If no, the message waits in the Vault, safe and unread, until you open it on your own schedule. Nothing is ever deleted. Nothing is ever lost. You decide what counts as urgent, and Sovereign learns from you over time.
Every message passes through three gates in order. The first gate that says "urgent" wins.
A message arrives
│
▼
┌───────────────┐ Is the sender on your VIP list?
│ 1. The Council│ ── yes ──▶ SMS to your phone
└───────────────┘
│ no
▼
┌───────────────┐ Does it match one of your rules?
│ 2. The Decrees│ ── yes ──▶ SMS to your phone (or deliberately held)
└───────────────┘
│ no
▼
┌───────────────┐ Does the AI think it's urgent for you?
│ 3. The Advisor│ ── yes ──▶ SMS to your phone
└───────────────┘
│ no
▼
The Vault (held, waiting for you)
If no gate claims urgency, the message waits in the Vault. Your phone stays silent.
| Page | What it covers |
|---|---|
| Installation | Prerequisites, cloning the repository, running setup.sh, first boot |
| Configuration | The .env file explained, every variable, minimum viable config |
| First run | Setting your password, building your first Council, what to expect |
| SMS gateways | Twilio, InfiniReach, Android HTTP gateway, gammu — which to choose and why |
On Telegram: Sovereign uses a bot, not your personal Telegram account. People reach you by messaging your bot. This is different from WhatsApp and Instagram, where they message the real you.
On the first message from a new contact: The first WhatsApp or Instagram message in a brand-new chat may not come through. The second one will. This is a known Matrix bridge behavior, not a bug.
On group messages: They are held by default, even if they contain urgency keywords. That is intentional. The Hold all group messages Decree sits at priority 1, checked before any keyword rule. To let one specific person through a noisy group, add them to your Council.
On the Advisor: It takes weeks to become useful. Give it time. At Level 4 it knows your patterns well enough to catch things your Decrees miss. You can reset it to zero at any time with no data retained.
On the WhatsApp session: The bridge stays linked like WhatsApp Web. Your phone needs to go online at least once every 14 days or the session unlinks. If you keep your smartphone at home on WiFi, this is not a problem.
On Colombia and similar markets: Cloud long codes from Twilio and other US/EU providers are subject to A2P filtering in some countries, which blocks foreign numbers from reaching local phones. The InfiniReach and Android HTTP gateways both use a phone's local SIM, making SMS local-to-local and avoiding this filter entirely.
Sovereign never silently drops a message. Every message either passes through or is held in the Vault. Nothing is deleted. Nothing is lost.
This is non-negotiable. It is in the code, not just the documentation.
Start the stack:
docker compose up -d
Start with WhatsApp and Instagram:
docker compose --profile whatsapp up -d
Common operations:
make logs # tail all service logs
make status # show running containers and health
make backup # dump SQLite DB to ./backups/
make update # pull latest images and rebuild
make ollama-pull # pull the Ollama LLM model
SMS commands from your dumb phone:
r Sounds good, talk soon → reply to most recent urgent message
r mama I'll be home at 6 → reply to last message from "mama"
r 2 On my way → reply to 2nd most recent message
list → see recent held messages
read 3 → read full content of message 3
status → vault summary
- New to Sovereign? Start with Installation, then First run.
- WhatsApp is the priority? After installation, go straight to WhatsApp setup.
- Not technical? The User Guide in the repository (docs/USER_GUIDE.md) is written in plain language for non-technical users. Every screen, every setting, explained with examples.
- Something broken? Check Troubleshooting first, then bring it to Discussions.
- Want to contribute? See Contributing.
Sovereign. Govern your attention.
Repository: github.com/zerohashcrbn/sovereign-stack Community: staysovereign.io License: AGPL-3.0
# SovereignReclaim the right to be unreachable.
Sovereign is a self-hosted personal communication router. It sits between you and your digital world — WhatsApp, Instagram, Telegram, email, SMS — evaluates every incoming message, and either delivers it to your dumb phone as a plain SMS or holds it quietly in the Vault until you choose to engage.
No managed cloud. No subscription. No company holding your messages.
This is the knowledge base for everyone running their own Realm. It covers everything from first installation to fine-tuning your Decrees after months of use. It is written in two registers: technical where it needs to be, plain language everywhere else.
If you are brand new, start at the top and read in order. If you are looking for something specific, the index below will get you there.
All day, messages arrive from many places. Sovereign reads each one and asks a single question: does this need to reach me right now? If yes, a short SMS goes to your simple phone — the only time it makes a sound. If no, the message waits in the Vault, safe and unread, until you open it on your own schedule. Nothing is ever deleted. Nothing is ever lost. You decide what counts as urgent, and Sovereign learns from you over time.
Every message passes through three gates in order. The first gate that says "urgent" wins.
A message arrives
│
▼
┌───────────────┐ Is the sender on your VIP list?
│ 1. The Council│ ── yes ──▶ SMS to your phone
└───────────────┘
│ no
▼
┌───────────────┐ Does it match one of your rules?
│ 2. The Decrees│ ── yes ──▶ SMS to your phone (or deliberately held)
└───────────────┘
│ no
▼
┌───────────────┐ Does the AI think it's urgent for you?
│ 3. The Advisor│ ── yes ──▶ SMS to your phone
└───────────────┘
│ no
▼
The Vault (held, waiting for you)
If no gate claims urgency, the message waits in the Vault. Your phone stays silent.
| Page | What it covers |
|---|---|
| Installation | Prerequisites, cloning the repository, running setup.sh, first boot |
| Configuration | The .env file explained, every variable, minimum viable config |
| First run | Setting your password, building your first Council, what to expect |
| SMS gateways | Twilio, InfiniReach, Android HTTP gateway, gammu — which to choose and why |
| Page | What it covers |
|---|---|
| WhatsApp setup | Matrix bridge (mautrix-whatsapp), step-by-step from zero to working |
| Instagram setup | mautrix-meta, session cookies, adding a second bridge to Synapse |
| Telegram setup | Creating a bot via BotFather, privacy settings for groups |
| Email setup | IMAP IDLE, startup scan limit, tuning for large inboxes |
| SMS connector | Receiving SMS as a platform (Twilio webhook) |
| Page | What it covers |
|---|---|
| The Vault | Waiting vs Retrieved tabs, reading messages, how it signals the Advisor |
| The Council | Adding members, per-member quiet hours override, the soft cap |
| The Decrees | Priority ordering, first-match logic, default Decrees, worked examples |
| The Advisor | Maturity levels, what it watches, what it never reads, how to reset |
| The Chronicle | Reading your decision log, understanding pass/hold/gate columns |
| Settings | Quiet hours, timezone, flood override |
| Page | What it covers |
|---|---|
| SMS commands | Full command reference, the 15-minute reply window |
| Quiet hours | Global window, per-person exceptions, flood override |
| Backups | make backup, what is saved, restore procedure |
| Updates | make update, what changes between versions, migration notes |
| Troubleshooting | Common symptoms, known behaviors, where to look in logs |
| Page | What it covers |
|---|---|
| Architecture | All seven layers, the internal message schema, flow diagrams |
| Hardware guide | VPS, home server, Raspberry Pi + GSM modem — full sovereignty options |
| The Advisor in depth | How the behavioral model works, maturity progression, privacy guarantees |
| Sharing Decrees | How to export, import, and contribute Decrees to the Commonwealth |
| Contributing | How to contribute code, documentation, or Decree sets |
Sovereign uses a deliberate language. These terms appear throughout the Wiki.
| Term | Meaning |
|---|---|
| The Council | Your VIP list. Small by design (soft cap: 10). Their messages always reach you, skipping every check. |
| The Decrees | Your rules. Priority-ordered. Lower number checked first. First match wins. |
| The Advisor | Local AI behavioral model (Ollama). Learns from your response patterns. Never reads content. |
| The Vault | Everything held. Two tabs: Waiting and Retrieved. Nothing ever deleted. |
| The Chronicle | Read-only log of every Sovereign decision. No scores, no streaks. |
| The Realm | Your Sovereign instance — your config, your data, your rules. |
| The Territory | Your dumb phone. The calm device that is your primary interface with the world. |
| The Commonwealth | The Sovereign community sharing Decrees, setups, and insights. |
On Telegram: Sovereign uses a bot, not your personal Telegram account. People reach you by messaging your bot. This is different from WhatsApp and Instagram, where they message the real you.
On the first message from a new contact: The first WhatsApp or Instagram message in a brand-new chat may not come through. The second one will. This is a known Matrix bridge behavior, not a bug.
On group messages: They are held by default, even if they contain urgency keywords. That is intentional. The Hold all group messages Decree sits at priority 1, checked before any keyword rule. To let one specific person through a noisy group, add them to your Council.
On the Advisor: It takes weeks to become useful. Give it time. At Level 4 it knows your patterns well enough to catch things your Decrees miss. You can reset it to zero at any time with no data retained.
On the WhatsApp session: The bridge stays linked like WhatsApp Web. Your phone needs to go online at least once every 14 days or the session unlinks. If you keep your smartphone at home on WiFi, this is not a problem.
On Colombia and similar markets: Cloud long codes from Twilio and other US/EU providers are subject to A2P filtering in some countries, which blocks foreign numbers from reaching local phones. The InfiniReach and Android HTTP gateways both use a phone's local SIM, making SMS local-to-local and avoiding this filter entirely.
Sovereign never silently drops a message. Every message either passes through or is held in the Vault. Nothing is deleted. Nothing is lost.
This is non-negotiable. It is in the code, not just the documentation.
Start the stack:
docker compose up -dStart with WhatsApp and Instagram:
docker compose --profile whatsapp up -dCommon operations:
make logs # tail all service logs
make status # show running containers and health
make backup # dump SQLite DB to ./backups/
make update # pull latest images and rebuild
make ollama-pull # pull the Ollama LLM modelSMS commands from your dumb phone:
r Sounds good, talk soon → reply to most recent urgent message
r mama I'll be home at 6 → reply to last message from "mama"
r 2 On my way → reply to 2nd most recent message
list → see recent held messages
read 3 → read full content of message 3
status → vault summary
- New to Sovereign? Start with Installation, then First run.
- WhatsApp is the priority? After installation, go straight to WhatsApp setup.
- Not technical? The User Guide in the repository (docs/USER_GUIDE.md) is written in plain language for non-technical users. Every screen, every setting, explained with examples.
- Something broken? Check Troubleshooting first, then bring it to Discussions.
- Want to contribute? See Contributing.
Sovereign. Govern your attention.
Repository: [github.com/zerohashcrbn/sovereign-stack](https://github.com/zerohashcrbn/sovereign-stack) Community: [staysovereign.io](https://staysovereign.io) License: AGPL-3.0