firefrost-gaming/firefrost-operations-manual
3
0
Fork 0
Code Issues 146 Pull Requests Packages Projects Releases Wiki Activity

docs: Update Trinity Core docs — correct 8GB RAM, add v2.1.0 changes

Browse Source 
- Hardware: Pi 4B is 8GB, not 4GB as previously documented
- OS: Debian GNU/Linux 13 (Trixie) aarch64, kernel 6.12.75
- Added deployment procedure (curl from Gitea API)
- Updated server table with trinity-core localhost entry
- Added version history table
- Updated future enhancements checklist
- Source code now in firefrost-services repo

Chronicler #78 | firefrost-operations-manual
This commit is contained in:
Claude
2026-04-11 10:07:47 +00:00
parent cb6e381511
commit 158e6e2fe6
1 changed files with 81 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
docs/infrastructure/trinity-core.md
View File

@@ -2,15 +2,18 @@
## Overview
Trinity Core is a Raspberry Pi 4B running in Michael's home network, providing a secure bridge for Claude to execute commands on Firefrost infrastructure.
Trinity Core is a Raspberry Pi 4B running in Michael's home network, providing a secure bridge for Claude to execute commands on Firefrost infrastructure. As of v2.1.0, Trinity Core can also audit itself via local execution.
**Deployed:** April 11, 2026 by Chronicler #76
**v2.1.0:** April 11, 2026 by Chronicler #78 (local execution, git version control)
## Hardware
- **Device:** Raspberry Pi 4B (4GB)
- **Storage:** 16GB SD card
- **OS:** Raspberry Pi OS Lite (64-bit)
- **Device:** Raspberry Pi 4B (8GB)
- **Storage:** 16GB SD card (4.4GB used, 33%)
- **OS:** Debian GNU/Linux 13 (Trixie) aarch64
- **Kernel:** 6.12.75+rpt-rpi-v8
- **CPU:** Cortex-A72, 4 cores
- **Hostname:** `trinity-core`
- **Local access:** `ssh claude_executor@trinity-core.local`
- **Network:** WiFi (TheDungeon) with ethernet backup option
@@ -19,51 +22,87 @@ Trinity Core is a Raspberry Pi 4B running in Michael's home network, providing a
```
Claude → mcp.firefrostgaming.com → Cloudflare Tunnel → Trinity Core → SSH → Target Server
→ local exec (trinity-core)
```
## Endpoint
- **URL:** `https://mcp.firefrostgaming.com`
- **Health check:** `GET /` (no auth)
- **List servers:** `GET /servers` (requires auth)
- **Execute command:** `POST /exec` (requires auth)
- **MCP SSE:** `GET /mcp` (Claude.ai connector)
- **MCP Messages:** `POST /mcp/messages` (Claude.ai connector)
- **OAuth Discovery:** `GET /.well-known/oauth-protected-resource`
## Authentication
- **Type:** Bearer token
- **Type:** Bearer token (via OAuth shim for Claude.ai)
- **Token:** `FFG-Trinity-2026-Core-Access`
- **Header:** `Authorization: Bearer FFG-Trinity-2026-Core-Access`
- **OAuth Client ID:** `trinity-core`
- **OAuth Client Secret:** `FFG-Trinity-2026-Core-Access`
## Registered Servers
| Name | Host | User |
|------|------|------|
| command-center | 63.143.34.217 | root |
| tx1-dallas | 38.68.14.26 | root |
| nc1-charlotte | 216.239.104.130 | root |
| panel-vps | 45.94.168.138 | root |
| dev-panel | 64.50.188.128 | root |
| wiki-vps | 64.50.188.14 | architect |
| services-vps | 38.68.14.188 | root |
| Name | Host | User | Type |
|------|------|------|------|
| command-center | 63.143.34.217 | root | SSH |
| tx1-dallas | 38.68.14.26 | root | SSH |
| nc1-charlotte | 216.239.104.130 | root | SSH |
| panel-vps | 45.94.168.138 | root | SSH |
| dev-panel | 64.50.188.128 | root | SSH |
| wiki-vps | 64.50.188.14 | architect | SSH |
| services-vps | 38.68.14.188 | root | SSH |
| trinity-core | localhost | claude_executor | Local |
## Usage Examples
## MCP Tools
### Health check
| Tool | Description |
|------|-------------|
| `list_servers` | Returns available Firefrost servers |
| `run_command` | Execute command on any server (SSH or local) |
## Source Code
**Git repo:** `firefrost-services` → `services/trinity-core/`
**Production location:** `/home/claude_executor/mcp-server/` on the Pi
### Deployment Procedure
1. Edit code in `firefrost-services/services/trinity-core/`
2. Commit and push to Gitea
3. SSH to the Pi:
```bash
curl https://mcp.firefrostgaming.com
ssh claude_executor@trinity-core.local
```
### List servers
4. Back up current version:
```bash
curl -H "Authorization: Bearer FFG-Trinity-2026-Core-Access" https://mcp.firefrostgaming.com/servers
cd ~/mcp-server
cp index.js index.js.bak
```
### Execute command
5. Fetch new code from Gitea:
```bash
curl -X POST https://mcp.firefrostgaming.com/exec \
-H "Content-Type: application/json" \
-H "Authorization: Bearer FFG-Trinity-2026-Core-Access" \
-d '{"server":"command-center","command":"hostname"}'
curl -s -H "Authorization: token e0e330cba1749b01ab505093a160e4423ebbbe36" \
"https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-services/raw/services/trinity-core/index.js?ref=main" \
-o index.js
```
6. Check if package.json changed (if so, run npm install):
```bash
curl -s -H "Authorization: token e0e330cba1749b01ab505093a160e4423ebbbe36" \
"https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-services/raw/services/trinity-core/package.json?ref=main" \
-o package.json.new
diff package.json package.json.new && rm package.json.new || (mv package.json.new package.json && npm install)
```
7. Restart service:
```bash
sudo systemctl restart mcp-server
```
8. Verify:
```bash
sudo systemctl status mcp-server
```
## Services
@@ -71,7 +110,7 @@ curl -X POST https://mcp.firefrostgaming.com/exec \
Both services are enabled and auto-start on boot:
- **cloudflared** — Cloudflare Tunnel to expose MCP endpoint
- **mcp-server** — Node.js Express server handling requests
- **mcp-server** — Node.js Express server (v2.1.0, SDK 1.29.0)
### Service management
```bash
@@ -94,6 +133,7 @@ tail -f ~/mcp-server/command.log
| File | Path |
|------|------|
| MCP server code | `/home/claude_executor/mcp-server/index.js` |
| Package manifest | `/home/claude_executor/mcp-server/package.json` |
| Command log | `/home/claude_executor/mcp-server/command.log` |
| Cloudflare config | `/etc/cloudflared/config.yml` |
| Cloudflare credentials | `/etc/cloudflared/*.json` |
@@ -105,9 +145,20 @@ tail -f ~/mcp-server/command.log
- **Tunnel ID:** 446d70b0-abd1-4ec7-8e06-6c277f99cbc7
- **Routes:** mcp.firefrostgaming.com → localhost:3000
## Version History
| Version | Date | Chronicler | Changes |
|---------|------|------------|---------|
| 1.0.0 | Apr 10, 2026 | #76 The Bridgekeeper | Initial deployment, SSH to 7 servers |
| 2.0.0 | Apr 11, 2026 | #77 The Socket | Claude.ai MCP connector, OAuth shim, SDK 1.29.0 |
| 2.1.0 | Apr 11, 2026 | #78 | Local self-execution, added to firefrost-services repo |
## Future Enhancements
- [x] ~~Claude MCP connector integration~~ (v2.0.0)
- [x] ~~Self-audit capability~~ (v2.1.0)
- [x] ~~Git version control~~ (v2.1.0)
- [ ] Discord notifications for command execution
- [ ] Claude MCP connector integration
- [ ] Command allowlist/categories
- [ ] Rate limiting
- [ ] Move token to environment variable