# Matrix/Conduit Execution Runbook

> Issue: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166) | Scaffold: [#183](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/183) | Decisions: [#187](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/187)
> Issued by: Ezra, Archivist | Date: 2026-04-05

## Mission
Deploy a sovereign Matrix/Conduit homeserver for encrypted human-to-fleet communication.

## Current State

| Phase | Status | Blocker |
|-------|--------|---------|
| Scaffold | Complete | None |
| Host selection | Blocked | #187 |
| DNS + TLS | Blocked | #187 |
| Deployment | Ready | Host provisioning |
| Room creation | Ready | Post-deployment |
| Telegram cutover | Ready | Fleet readiness |

## Prerequisites Checklist (from #187)

- [ ] **Host**: Confirm VPS (Hermes, Allegro, or new)
- [ ] **Domain**: Register `matrix.timmy.foundation` (or chosen domain)
- [ ] **DNS**: A record → server IP
- [ ] **Ports**: 80, 443, 8448 available and open
- [ ] **Reverse Proxy**: Caddy or Nginx installed
- [ ] **Docker**: Engine + Compose >= v2.20

## Execution Steps

### Step 1: Host Provisioning
```bash
./infra/matrix/host-readiness-check.sh matrix.timmy.foundation
```

### Step 2: DNS Configuration
```
matrix.timmy.foundation.    A    <SERVER_IP>
```

### Step 3: Deploy Conduit
```bash
cd infra/matrix
cp .env.example .env
# Edit .env and conduit.toml with your domain
./deploy-matrix.sh matrix.timmy.foundation
```

### Step 4: Verify Homeserver
```bash
curl https://matrix.timmy.foundation/_matrix/client/versions
```

### Step 5: Create Operator Room
1. Open Element Web
2. Register/login as `@alexander:matrix.timmy.foundation`
3. Create encrypted room: `#fleet-ops:matrix.timmy.foundation`

### Step 6: Telegram Cutover Plan
1. Run both Telegram and Matrix in parallel for 7 days
2. Pin Matrix room as primary in Telegram
3. Disable Telegram gateway only after all agents confirm Matrix connectivity

## Operational Commands

| Task | Command |
|------|---------|
| Check health | `./host-readiness-check.sh` |
| View logs | `docker compose logs -f conduit` |
| Backup data | `tar czvf conduit-backup-$(date +%F).tar.gz data/conduit/` |
| Update image | `docker compose pull && docker compose up -d` |

— Ezra, Archivist