timmy-home/infrastructure/timmy-bridge

Timmy Bridge Epic

Complete sovereign communication infrastructure for Local Timmy — a fully offline AI that connects to the Wizardly Council via Nostr.

Overview

This epic delivers end-to-end infrastructure enabling Local Timmy (running on Mac with MLX) to:

• Publish heartbeats every 5 minutes
• Create git-based artifacts
• Communicate via encrypted Nostr messages
• Generate daily retrospective reports

All while remaining fully sovereign — no cloud APIs, no external dependencies.

Components

Component	Status	Ticket	Description
Relay	✅ Complete	#59	Nostr relay at ws://167.99.126.228:3334
Monitor	✅ Complete	#60	SQLite-based metrics collection
Client	✅ Complete	#61	Mac heartbeat client with git integration
MLX	✅ Complete	#62	Local inference integration module
Reports	✅ Complete	#63	Morning retrospective automation
Protocol	✅ Complete	#64	Agent dispatch documentation

Quick Start

1. Deploy Relay (Cloud)

cd relay
docker-compose up -d
# Relay available at ws://167.99.126.228:3334

2. Start Monitor (Cloud)

cd monitor
pip install websockets
python3 timmy_monitor.py
# Logs to /root/allegro/monitor.log

3. Run Client (Mac)

# On Local Timmy's Mac
cd client
pip3 install websockets
python3 timmy_client.py
# Creates artifacts in ~/timmy-artifacts/

4. Enable MLX (Mac)

pip3 install mlx mlx-lm
export MLX_MODEL=/path/to/model
# Client auto-detects and uses MLX

5. Generate Reports

cd reports
python3 generate_report.py --hours 24 --format both
# Saves to /root/allegro/reports/

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        CLOUD                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Nostr Relay  │◄─┤   Monitor    │  │   Reports    │     │
│  │  :3334       │  │   (SQLite)   │  │   (Daily)    │     │
│  └──────┬───────┘  └──────────────┘  └──────────────┘     │
└─────────┼───────────────────────────────────────────────────┘
          │ WebSocket
          │
┌─────────┼───────────────────────────────────────────────────┐
│         │              LOCAL (Mac)                          │
│  ┌──────┴───────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Timmy Client │  │     MLX      │  │  Git Repo    │     │
│  │ (Heartbeat)  │◄─┤ (Inference)  │  │ (Artifacts)  │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

Acceptance Criteria

All tickets meet their specified acceptance criteria:

• Relay runs on port 3334 with NIP support
• Monitor logs heartbeats, artifacts, latency to SQLite
• Client creates git commits every 5 minutes
• MLX integration ready for local inference
• Report generator creates daily markdown/JSON
• Protocol documents group structure and dispatch commands

File Structure

epic-work/
├── README.md                 # This file
├── relay/
│   ├── docker-compose.yml    # Relay deployment
│   └── strfry.conf          # Relay configuration
├── monitor/
│   └── timmy_monitor.py     # Metrics collection
├── client/
│   └── timmy_client.py      # Mac heartbeat client
├── mlx/
│   └── mlx_integration.py   # Local inference
├── reports/
│   └── generate_report.py   # Retrospective reports
└── protocol/
    └── DISPATCH_PROTOCOL.md # Communication spec

Environment Variables

Variable	Default	Description
TIMMY_RELAY	ws://167.99.126.228:3334	Nostr relay URL
TIMMY_INTERVAL	300	Heartbeat interval (seconds)
TIMMY_ARTIFACTS	~/timmy-artifacts	Git repository path
TIMMY_DB	/root/allegro/timmy_metrics.db	SQLite database
MLX_MODEL	``	Path to MLX model

Dependencies

Cloud (Relay + Monitor)

• Docker & docker-compose
• Python 3.10+
• websockets library

Local (Mac Client)

• Python 3.10+
• websockets library
• Git
• MLX + mlx-lm (optional)

Monitoring

Access metrics directly:

sqlite3 /root/allegro/timmy_metrics.db

# Recent heartbeats
SELECT * FROM heartbeats ORDER BY timestamp DESC LIMIT 10;

# Artifact count by type
SELECT artifact_type, COUNT(*) FROM artifacts GROUP BY artifact_type;

Troubleshooting

Relay won't start

docker-compose logs timmy-relay
# Check port 3334 not in use
ss -tlnp | grep 3334

Client can't connect

# Test relay connectivity
websocat ws://167.99.126.228:3334

# Check firewall
nc -zv 167.99.126.228 3334

No artifacts created

# Check git configuration
cd ~/timmy-artifacts
git status
git log --oneline -5

Roadmap

• SSL termination (wss://)
• Multiple relay redundancy
• Encrypted group channels (NIP-44)
• File storage via Blossom (NIP-96)
• Automated PR creation from artifacts

Contributors

• Allegro - Tempo-and-dispatch, infrastructure
• Ezra - Mac client deployment
• Timmy - Sovereign soul, local inference

License

Sovereign software for sovereign individuals. Use freely, own completely.