README.md
Rama main · réplica de lectura del repositorio original.
# fusionAIze Grid (faigrid)
[](https://github.com/fusionAIze/faigrid/actions/workflows/repo-safety.yml)
[](https://github.com/fusionAIze/faigrid/actions/workflows/lint.yml)
[](https://github.com/fusionAIze/faigrid/actions/workflows/test.yml)
[](https://github.com/fusionAIze/faigrid/releases)
[](https://opensource.org/licenses/Apache-2.0)
[](https://openclaw.ai/)
[](https://n8n.io/)
[](https://www.docker.com/)
[](https://www.gnu.org/software/bash/)
> **The sovereign execution substrate for AI-native operations.**
**fusionAIze Grid** defines *where* AI-native work runs, under *what constraints*, with *what isolation*, through which *queues and runners*, and with which *observability and recovery patterns*. It is the execution layer of the fusionAIze ecosystem — not the context, memory, or routing layer.
---
### Navigation
[Ecosystem](#the-ecosystem) •
[Architecture](#architecture) •
[Quick Start](#quick-start) •
[Grid Modules](#grid-modules) •
[Workbench](#workbench-plugins) •
[Messenger](#grid-messenger) •
[Repository Layout](#repository-layout) •
[Troubleshooting](#troubleshooting) •
[License](#license)
---
## The Ecosystem
`faigrid` is part of the fusionAIze 5-layer product architecture that operationalizes human-AI fusion teams:
| Layer | Repo | Role |
|---|---|---|
| **Gate** | `faigate` | AI-native gateway for models, providers, tools and clients |
| **Lens** | `failens` | Compression, translation, and context-focusing |
| **Fabric** | `faifabric` | Shared context, memory, and knowledge |
| **Grid** | `faigrid` ← | Sovereign execution substrate |
| **Signal** | `faisignal` | Observability, monitoring, and signal layer |
| **OS** | `fusionAIzeOS` | Operating logic for human-AI fusion teams |
faigrid feeds **runtime health signals** (runner failures, service state, queue backlog, job completion) directly into fusionAIze Signal for cross-layer operational intelligence.
---
## Architecture
The infrastructure relies on a decoupled, secure **4+1 Node Architecture**:
```
Public Internet
│ (HTTPS)
┌─────────────────────▼─────────────────────┐
│ GRID EDGE │ (1) Ingress / Proxy
│ Caddy Reverse Proxy · Pi-hole DNS · SSO │
└─────────────────────┬─────────────────────┘
│ (Internal TLS / .grid)
┌─────────────────────▼─────────────────────┐
│ GRID CORE │ (2) Trusted Internal Services
│ n8n · openclaw · codenomad · faigate │
│ grid-messenger · Postgres · Redis │
└──────┬─────────────────────────────┬──────┘
│ (Local API) │ (Encrypted Tunnels)
┌──────────▼──────────┐ ┌──────────▼──────────┐
│ GRID WORKER │ │ GRID EXTERNAL │ (5) Cloud Model Bridges
│ Local LLM · Ollama │ │ Cloud VPS Node │
└──────────┬──────────┘ └─────────────────────┘
│
┌──────────▼──────────┐
│ GRID BACKUP │ (4) Observability & Recovery
│ Synology · Restic │
└─────────────────────┘
```
**Execution Classes** — Grid's core abstraction:
| Class | Where | What |
|---|---|---|
| Edge Ingress | grid-edge | TLS termination, reverse proxy, DNS, auth |
| Trusted Internal | grid-core | n8n, APIs, orchestration, messaging |
| Queued Automations | grid-core | Workflow engine, background tasks |
| Local Model Workers | grid-worker | Ollama, LM Studio, LAN-only inference |
| Cloud Model Bridges | grid-external | Egress-controlled cloud reasoning |
| Recovery Base | grid-backup | Automated immutable backup pipelines |
---
## Quick Start
```bash
# Clone and provision (detects macOS/Linux automatically)
git clone https://github.com/fusionAIze/faigrid.git && cd faigrid
bash install.sh
# Deploy a specific role, e.g. Core
./install.sh --mode local --role core --yes
```
**Flags:**
- `--yes` auto-confirms **non-destructive** prompts (role selection, mode, VNC, reinstall-over-nothing, etc.).
- `--force` bypasses **destructive** overwrite/wipe prompts.
- The uninstall `delete-all-data` confirmation is **always** required verbatim — no flag bypasses it.
Node registry is stored at `~/.config/faigrid/registry/` and persists across reinstalls and Homebrew upgrades.
```bash
# Open the interactive Workbench
./core/workbench/scripts/control.sh
# Run diagnostics
./scripts/grid-doctor.sh
# Check live logs
tail -f /var/log/faigrid/grid-system.log
```
---
## Grid Modules
| Module | Role | Services |
|---|---|---|
| **grid-edge** | Public gatekeeper | Caddy, Pi-hole, CrowdSec, SSO |
| **grid-core** | Private compute substrate | n8n, openclaw, codenomad, faigate, grid-messenger |
| **grid-worker** | Isolated execution | Ollama, LM Studio, shell runners |
| **grid-backup** | Safety net | Restic, Synology, automated snapshots |
| **grid-external** | Cloud bridge | Egress-aware VPS, external model access |
---
## Workbench Plugins
The **Grid Workbench** (`core/workbench/`) is the interactive operator console for managing services on each node. Plugins are self-contained Bash modules with a standard interface (`tool_configure`, `tool_doctor`, `tool_update`).
**Current plugin registry:**
| Plugin | Category | Purpose |
|---|---|---|
| `n8n` | automation | Workflow engine — install, configure, manage |
| `openclaw` | agents | OpenClaw agent runtime — deploy, update, doctor |
| `codenomad` | agents | Codenomad coding agent — configure, manage |
| `faigate` | gateway | fusionAIze Gate — install, configure, health |
| `caddy` | proxy | Internal LAN reverse proxy — `.grid` TLD + Pi-hole DNS |
| `grid-messenger` | comms | Telegram decision bridge — configure, health |
Plugin categories: `agents/` · `automation/` · `proxy/` · `comms/`
---
## Grid Messenger
`grid-messenger` is the **Telegram decision and notification bridge** for the Grid. It runs as a systemd service on grid-core and exposes a local HTTP API (`127.0.0.1:9119`) that any registered app (n8n, openclaw, codenomad, etc.) can call to push decisions or notifications.
**Three decision types:**
| Type | UI | Use case |
|---|---|---|
| `approve` | Approve / Reject buttons | Binary gate — deploy, merge, confirm |
| `choice` | N labelled buttons | Multi-option selection — which agent, which branch |
| `input` | Free-text capture | User-supplied values — target dir, config input |
**App registry** — each app (openclaw, codenomad, n8n, …) registers with a display name, emoji, and optional Telegram topic thread ID for sub-channel routing.
```bash
# HTTP API (from any app on grid-core)
POST http://127.0.0.1:9119/decision/request
POST http://127.0.0.1:9119/notify
POST http://127.0.0.1:9119/app/register
GET http://127.0.0.1:9119/health
```
See `core/messenger/` for installation and configuration details.
---
## Repository Layout
```
faigrid/
├── install.sh # Root orchestrator (state-aware)
├── core/
│ ├── workbench/
│ │ └── scripts/
│ │ ├── control.sh # Interactive Workbench CLI
│ │ ├── _lib.sh # Shared helpers
│ │ ├── _projects.sh # Project/repo manager
│ │ ├── _skills.sh # AI skill deployer
│ │ └── plugins/
│ │ ├── agents/ # openclaw, codenomad
│ │ ├── automation/ # n8n
│ │ ├── proxy/ # caddy
│ │ └── comms/ # grid-messenger
│ └── messenger/
│ ├── src/grid_messenger.py # Telegram bot service
│ ├── install.sh # Messenger installer
│ ├── systemd/ # Service unit
│ └── requirements.txt
├── docs/
│ ├── ROADMAP.md
│ ├── IMPLEMENTATION-PLAN.md
│ ├── architecture/
│ ├── runbooks/
│ └── reference/
├── scripts/
│ ├── grid-doctor.sh
│ ├── grid-dashboard.sh
│ ├── grid-deploy.sh
│ ├── grid-watchdog.sh
│ └── faigrid-release
├── tests/
│ └── smoke/
└── .github/
└── workflows/ # lint, test, release-please, codeql, repo-safety
```
---
## Troubleshooting
```bash
# Comprehensive health check
./scripts/grid-doctor.sh
# Live system log
tail -f /var/log/faigrid/grid-system.log
# Workbench plugin doctor (per-service)
./core/workbench/scripts/control.sh doctor
```
Common issues:
| Symptom | Cause | Fix |
|---|---|---|
| `no registered nodes` after Homebrew install | OLD: registry was repo-relative | Registry migrated to `~/.config/faigrid/registry/` in v1.6.0 |
| `.grid` domains not resolving | Pi-hole DNS not set as resolver | Set workstation DNS to Edge LAN IP |
| `grid-messenger` decisions not arriving | Bot token or chat ID missing | Run Workbench → comms → grid-messenger → configure |
---
## Security
- All core services bind to `127.0.0.1` — never exposed beyond localhost/LAN without explicit edge config.
- Secrets live in `.env` files outside the repo. Never committed. `.gitignore` covers all credential patterns.
- Services run as dedicated system users (no login shell, no home dir). See `CLAUDE.md` for the full system user pattern.
- Destructive operations (uninstall, wipe, volume removal) always prompt for confirmation.
---
## License
Apache 2.0 — see [LICENSE](LICENSE) for details.
---
> Made with ❤️ in Berlin · Part of the [fusionAIze](https://github.com/fusionAIze) ecosystem
## Repository & Contributing
Canonical repository: **self-hosted Forgejo** — `git.langevc.com/fusionaize/faigrid`
(`git clone git@git.langevc.com:fusionaize/faigrid.git`). Develop against the Forgejo
clone and open pull requests there. The GitHub copy is a read-only mirror.