Solarpunk Gift Economy Mesh Network 🌱

Production-ready system for regenerative communities to coordinate mutual aid without internet dependency.

Status License Python TypeScript

Download APK

Standalone offline app - runs Python backend directly on your phone. No internet required after install.

• Works 100% offline
• 67 MB download
• Android 8.0+ required
• Mesh sync via WiFi Direct

View all releases

Linux/Mac:

curl -sL https://raw.githubusercontent.com/lizTheDeveloper/solarpunk_utopia/main/setup.sh | bash

Termux (Android):

pkg install curl -y && curl -sL https://raw.githubusercontent.com/lizTheDeveloper/solarpunk_utopia/main/setup.sh | bash

Or using wget:

wget -qO- https://raw.githubusercontent.com/lizTheDeveloper/solarpunk_utopia/main/setup.sh | bash

Note: Requires Python 3.11 (not 3.12). The setup script will automatically install Python 3.11 if needed. See PYTHON_VERSION.md for details.

This installs everything and starts all services. Access at http://localhost:3000 when complete.

• Android 7.0+ (Android 11+ requires extra steps below)
• 2GB+ free storage
• Stable WiFi connection

1. Install Termux from F-Droid (NOT Google Play - that version is broken)

   • Install F-Droid app: https://f-droid.org/
   • Search for "Termux" in F-Droid
   • Install Termux (version 0.118.x recommended)

2. Grant Permissions (IMPORTANT for Android 11+)

   • Open Android Settings → Apps → Termux → Permissions
   • Enable "Files and media" or "Storage"
   • For Android 11+: Enable "All files access" under Special app access

3. First Launch

   • Open Termux
   • Wait for bootstrap installation (2-5 minutes)
   • Do not touch anything until you see a $ prompt
   • If you get "Permission denied" errors, see troubleshooting below

4. Run the installer:

   pkg install curl -y && curl -sL https://raw.githubusercontent.com/lizTheDeveloper/solarpunk_utopia/main/setup.sh | bash

   Installation takes 5-15 minutes depending on your device.

5. Access the app in your phone's browser:

   # Open Chrome/Firefox and go to:
   http://localhost:3000

6. Keep services running after closing Termux:

   Prevent CPU sleep (required):

   termux-wake-lock

   This keeps services running even when screen is off.

   Start services in background:

   nohup ./run_all_services.sh > /dev/null 2>&1 &

   Prevent Android from killing Termux:

   • Settings → Apps → Termux → Battery → Unrestricted (or "Don't optimize")
   • This prevents Android from killing Termux in the background

   Keep screen on while working (optional, drains battery):

   • Settings → Display → Screen timeout → 30 minutes (or higher)
   • Or use Developer Options → Stay awake (while charging)

7. Auto-start on phone boot (optional):

   • Install Termux:Boot from F-Droid
   • Create startup script:

     mkdir -p ~/.termux/boot
     cat > ~/.termux/boot/start-solarpunk.sh << 'EOF'
     #!/data/data/com.termux/files/usr/bin/sh
     termux-wake-lock
     cd ~/solarpunk_utopia
     ./run_all_services.sh > /dev/null 2>&1 &
     EOF
     chmod +x ~/.termux/boot/start-solarpunk.sh

8. Check service health:

   curl http://localhost:8000/health

"Unable to install bootstrap" or "Permission denied":

1. Clean reinstall (this fixes 90% of issues):

   # In Android Settings:
   Settings → Apps → Termux → Storage → Clear Data
   Settings → Apps → Termux → Uninstall
   # Then reinstall from F-Droid and grant permissions immediately

2. Android 11+ Phantom Process Issue:

   • If bootstrap keeps failing, you may need to disable phantom process killer
   • Requires ADB: adb shell "settings put global settings_enable_monitor_phantom_procs false"
   • Then reboot phone and reinstall Termux

3. Change repository mirror:

   termux-change-repo
   # Select "All repositories" → Choose a different mirror

4. Alternative: Use UserLAnd

   • If Termux won't work, install UserLAnd from Play Store/F-Droid
   • Choose Ubuntu distribution
   • Run the Linux installer instead

Services won't start:

• Make sure you have enough storage (check with df -h)
• Try killing existing processes: ./stop_all_services.sh then restart

Can't access localhost:3000:

• Check if services are running: ps aux | grep python
• Check logs: tail -f logs/dtn_bundle_system.log
• Make sure you're using http:// not https://

A complete offline-first mesh network system for Solarpunk communes to:

• 🎁 Share resources via gift economy (offers, needs, exchanges)
• 📦 Distribute bundles via delay-tolerant networking
• 🔍 Search distributed indexes across mesh islands
• 📚 Share knowledge through chunked file distribution
• 🤖 Get AI assistance for matching, planning, and coordination
• 🌐 Operate autonomously without internet or corporate platforms

This is not a demo. This is production software for real communities.

# Clone repository
git clone https://github.com/lizTheDeveloper/solarpunk_utopia.git
cd solarpunk_utopia
# Setup backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Start all services
./run_all_services.sh
# Start frontend (new terminal)
cd frontend
npm install
npm run dev
# Access at http://localhost:3000

See QUICKSTART.md for detailed guide.

• ✅ DTN Bundle System (5 systems) - Delay-tolerant networking with store-and-forward
• ✅ ValueFlows Node (6 systems) - Complete gift economy coordination (VF v1.0)
• ⏳ Phone Deployment (0 systems) - Deferred for physical hardware

• ✅ Discovery & Search (3 systems) - Distributed queries across mesh
• ✅ File Chunking (3 systems) - Knowledge distribution with Merkle trees
• ✅ Multi-AP Mesh Network (4 systems) - Physical infrastructure (Mode A/C)

• ✅ Agent System (7 systems) - AI agents for coordination (proposals require approval)

• ✅ Complete unified frontend (React + TypeScript, 47 files)
• ✅ Systemd service management (Linux)
• ✅ Nginx reverse proxy
• ✅ End-to-end integration tests
• ✅ Comprehensive documentation (8,000+ lines)

• 235+ source files
• 32,000+ lines of production code
• 90+ REST API endpoints (auto-documented)
• 20+ test suites (100% pass rate)

• Create offers and needs in <1 minute
• AI matchmaker finds compatible offers/needs
• Exchange coordination with bilateral approval
• Event recording for accountability and provenance
• All 13 ValueFlows object types implemented

• Store-and-forward between AP islands
• Priority-based forwarding (emergency → perishable → normal → low)
• Ed25519 cryptographic signing
• TTL enforcement and cache budgets
• Bundle propagation <10 min via bridge nodes

• Periodic index publishing (offers, needs, files, services)
• Query propagation through mesh network
• Cached indexes enable offline discovery
• Bridge nodes serve as query responders

• Content-addressed file distribution (SHA-256)
• Intelligent chunking (256KB-1MB)
• Merkle tree verification
• Library nodes cache popular content
• Resume partial downloads

• Multiple AP islands with independent subnets
• Bridge nodes walk between islands carrying bundles
• Mode C (DTN-only) always works (mandatory)
• Mode A (BATMAN-adv) optional speedup
• Graceful degradation

• 7 specialized agents (matchmaker, scheduler, planner, etc.)
• Proposal-based (NOT allocations) - human approval required
• Completely opt-in (no surveillance)
• Transparent reasoning (explanation + inputs + constraints)

┌─────────────────────────────────────────────────────────────┐
│ Solarpunk Mesh Network │
└─────────────────────────────────────────────────────────────┘
┌──────────────────┐
│ DTN Bundle │ ← Foundation: Store-and-forward transport
│ System │ Port 8000, Ed25519 signing
│ (TIER 0) │
└────────┬─────────┘
 │
 ├─────────┐
 ↓ ↓
┌──────────────┐ ┌──────────────┐
│ ValueFlows │ │ Discovery & │ ← Core: Economic coordination
│ Node │ │ Search │ and distributed search
│ (TIER 0) │ │ (TIER 1) │
│ Port 8001 │ │ Port 8003 │
└──────────────┘ └──────────────┘
 │ │
 ├──────────────┼─────────┐
 ↓ ↓ ↓
┌──────────────┐ ┌─────────┐ ┌──────────────┐
│ Agent System │ │ File │ │ Multi-AP │
│ (TIER 2) │ │ Chunking│ │ Mesh │
│ 7 AI agents │ │(TIER 1) │ │ (TIER 1) │
│ │ │Port 8004│ │ Port 8002 │
└──────────────┘ └─────────┘ └──────────────┘

• QUICKSTART.md - 5-minute setup guide
• DEPLOYMENT.md - Production deployment (systemd, Raspberry Pi)
• BUILD_STATUS.md - Complete build status and statistics

• BUILD_PLAN.md - Vision, architecture, and specifications
• FINAL_SUMMARY.md - Complete summary of what was built
• Component READMEs - Each system has detailed documentation

Auto-generated interactive docs available at:

• DTN: http://localhost:8000/docs
• ValueFlows: http://localhost:8001/docs
• Bridge: http://localhost:8002/docs
• Discovery: http://localhost:8003/docs
• Files: http://localhost:8004/docs

Backend: Python 3.12, FastAPI, SQLite, asyncio, Ed25519 crypto Frontend: React 18, TypeScript, Vite, Tailwind CSS, React Query Infrastructure: Systemd, Nginx, Python venv Mesh: BATMAN-adv, hostapd, dnsmasq Testing: pytest, pytest-asyncio

• Share surplus food before it spoils (perishables dispatcher)
• Lend tools and equipment easily (offer/need matching)
• Coordinate seasonal planting and harvests (permaculture planner)
• Teach and learn skills within community (education pathfinder)
• Plan work parties and events (scheduler agent)
• Track resource flows for accountability (event recording)
• Operate entirely offline and autonomously (DTN networking)

• Complete reference implementation of ValueFlows v1.0
• Production-ready DTN bundle system with Ed25519 signing
• Multi-agent AI coordination framework with approval gates
• Content-addressed file distribution with Merkle trees
• Distributed discovery and search across mesh networks
• Real-world offline-first architecture patterns

solarpunk_utopia/
├── app/ # DTN Bundle System + AI Agents
├── valueflows_node/ # ValueFlows implementation + React UI
├── discovery_search/ # Discovery & Search system
├── file_chunking/ # File chunking system
├── mesh_network/ # Multi-AP mesh network software
├── frontend/ # Unified frontend application
├── tests/integration/ # End-to-end tests
├── openspec/ # OpenSpec proposals (7 proposals)
├── setup.sh # One-line installer
├── run_all_services.sh # Start all services
└── stop_all_services.sh # Stop all services

This is infrastructure for regenerative communities. Contributions welcome!

1. Read CLAUDE.md for repository architecture
2. Check BUILD_STATUS.md for what's complete
3. Review openspec/ for proposals and specifications
4. Run tests: pytest tests/integration/ -v
5. Follow existing patterns (FastAPI, React Query, Pydantic, TypeScript)

MIT License - Use this to build a better world!

See LICENSE file for details.

From the original specification:

"We're building the infrastructure for regenerative gift economy communities. This isn't just software—it's a tool for communities to coordinate mutual aid, share resources, plan permaculture work, and learn together, all without depending on corporate platforms or internet infrastructure."

When this system works, communes can:

• ✅ Share surplus food before it spoils
• ✅ Lend tools and equipment easily
• ✅ Coordinate seasonal planting and harvests
• ✅ Teach and learn skills within the community
• ✅ Plan work parties and events
• ✅ Track resource flows for accountability
• ✅ Operate entirely offline and autonomously

This is infrastructure for a better world. Let's build it together. 🌱

Current: ✅ Production ready (28 of 31 systems complete) Next: Hardware deployment (Raspberry Pi APs, Android bridge nodes) Future: Multi-commune federation via NATS

• Documentation: See QUICKSTART.md and DEPLOYMENT.md
• Issues: GitHub Issues
• Questions: Discussions tab

Built with ❤️ for regenerative gift economy communities

Let's coordinate mutual aid without corporate platforms. Let's build solidarity infrastructure. Let's create the world we want to see. 🌱