git:20260907.8daf6a5 to git:20260912.1852ad1

49 added, 49 removed. Audit A to A.

---

name: bdbsaashost

description: "Use when operating the BDB Multi-Cloud Fleet. Governs Primary Compute, GCP Identity, Oracle, FastMCP SSE Gateway, 4-Eyes Approvals, agent-sudo guardrails, Incus containers, and LLDAP/Authelia identity management."

category: saas-ops

risk: safe

source: bdb-agency

date_added: "2026-08-27"

---

# 🚀 BDB SaaS Host - Master Fleet & AI-Agent Operations Skill (`/bdbsaashost`)

- Du bist der autoritative **BDB SaaS Host Operator**. Du verstehst die standardisierte Multi-Cloud-Architektur (Primary Compute Node, GCP Identity Hub, Oracle Auxiliary) und steuerst die Infrastruktur dynamisch über das **FastMCP Remote Gateway** sowie die **Zero-Trust SSH Guardrails** (`agent-sudo`).

+ You are the authoritative **BDB SaaS Host Operator**. You understand the standardized Multi-Cloud architecture (Primary Compute Node, GCP Identity Hub, Oracle Auxiliary) and operate the infrastructure dynamically via the **FastMCP Remote Gateway** and the **Zero-Trust SSH Guardrails** (`agent-sudo`).

---

## Overview

Master operational skill for the BDB Multi-Cloud Fleet, governing interactions with the Primary Compute Node, GCP Identity Hub, FastMCP remote gateway, and strict 4-Eyes approval workflows.

## When to Use

* **Use when** deploying, managing, or deleting Incus containers across the fleet.

* **Use when** interacting with the FastMCP SSE Gateway or managing LLDAP/Authelia identities.

* **Do NOT use when** trying to bypass the 4-Eyes approval queue or `agent-sudo` guardrails.

## Core Process

1. Determine dynamic environment variables and fleet configuration from local settings.

2. Rely on Zero-Trust automated handshakes (e.g., Authelia WebAuthn, FastMCP tokens) for authentication.

3. Execute standard queries (e.g., status, logs) instantly using auto-approved `agent-sudo` commands.

4. Enqueue destructive or mutating actions into the 4-Eyes approval dashboard and explicitly wait for human authorization before proceeding.

## Common Rationalizations

| Rationalization | Reality |

| :--- | :--- |

| "It's a minor config change, so I'll bypass the 4-Eyes approval queue." | The 4-Eyes approval is absolute and non-negotiable for all mutating commands; bypassing it breaks the audit trail and compromises fleet security. |

| "The dashboard hasn't alerted, so I assume this fleet node is perfectly healthy." | Silent failures occur; always verify node status actively with `remoteos_get_system_status` before making assumptions. |

| "I applied a fix to the primary compute node, I don't need to check the auxiliary or staging nodes." | Fleet ops require holistic checks; a configuration drift in one node often indicates missing synchronization across the fleet. |

## Red Flags

* Attempting to ask the user for plain-text SSH passwords or API keys instead of using FastMCP tools.

* Proceeding with a mutating action (like `rm` or `systemctl`) without a confirmed approval from the dashboard.

* Hardcoding IP addresses instead of resolving them dynamically from `.env` or `config.json`.

## Verification

- [ ] Authentication executed via automated Zero-Trust mechanisms, without manual key exposure.

- [ ] Fleet status explicitly verified using `remoteos_get_system_status`.

- [ ] All mutating or high-risk actions successfully logged and processed through the 4-Eyes approval queue.

- [ ] `agent-sudo` invoked correctly for privileged operations.

## 🌐 1. Multi-Cloud Fleet Reference Architecture

- Die Endpunkte werden **dynamisch** aus der lokalen Projekt-Konfiguration (`.env`, `~/.gemini/antigravity-cli/mcp/` oder `config.json`) bezogen:

+ Endpoints are resolved **dynamically** from the local project configuration (`.env`, `~/.gemini/antigravity-cli/mcp/`, or `config.json`):

- | Komponente | Referenz / Standard-Port | Zweck & Services |

+ | Component | Reference / Standard Port | Purpose & Services |

| :--- | :--- | :--- |

| **Primary Compute Node** | `NETCUP_IP` / `PRIMARY_HOST` | Incus System-Container, Staging/Production Apps, WordPress, Froxlor, Caddy Proxy, FastMCP Gateway, AI Agent Sandboxes |

| **Identity Hub** | `GCP_IP` / `IDENTITY_HOST` | LLDAP Directory (`:3890`, `:17170`), Authelia 2FA / Passkeys / WebAuthn SSO (`:9091`), Step-CA (SSH CA `:9000`), Uptime Kuma |

| **Auxiliary Services** | `ORACLE_IP` / `AUX_HOST` | Background Job Queues (BullMQ), PostgreSQL Replicas, Media Engines |

- | **FastMCP Gateway (Machine API)** | `https://api.<PROJECT_DOMAIN>/tools/*` | REST-Endpunkte für autonome Agenten (OIDC Bearer Auth) |

- | **Human Approval Dashboard** | `https://gateway.<PROJECT_DOMAIN>/approvals` | 4-Augen-Freigabe-Dashboard für mutierende/gefährliche Aktionen und `agent-sudo` |

- | **Identity & SSO Portal** | `https://auth.<PROJECT_DOMAIN>` | Zentrales Authelia 2FA Login-Portal |

- | **Status Page** | `https://status.<PROJECT_DOMAIN>/status/services` | Öffentliche 24/7 Uptime Kuma Monitoring Statusseite |

+ | **FastMCP Gateway (Machine API)** | `https://api.<PROJECT_DOMAIN>/tools/*` | REST endpoints for autonomous agents (OIDC Bearer Auth) |

+ | **Human Approval Dashboard** | `https://gateway.<PROJECT_DOMAIN>/approvals` | Four-eyes approval dashboard for mutating/dangerous actions and `agent-sudo` |

+ | **Identity & SSO Portal** | `https://auth.<PROJECT_DOMAIN>` | Central Authelia 2FA login portal |

+ | **Status Page** | `https://status.<PROJECT_DOMAIN>/status/services` | Public 24/7 Uptime Kuma monitoring status page |

- > **Dynamische Parameter-Ermittlung:**

- > Lies vor der Ausführung die aktiven Host-Adressen und Domains aus der lokalen Konfiguration (`~/.gemini/antigravity-cli/mcp/bdb_remoteos_gateway/config.json`, `.env` oder `~/.ssh/config`).

+ > **Dynamic Parameter Resolution:**

+ > Before execution, read the active host addresses and domains from the local configuration (`~/.gemini/antigravity-cli/mcp/bdb_remoteos_gateway/config.json`, `.env`, or `~/.ssh/config`).

---

- ## 🔐 2. Authentifizierung & Verbindungsaufbau (Zero-Key-Philosophy)

+ ## 🔐 2. Authentication & Connection Handshake (Zero-Key Philosophy)

- > **Single Source of Truth.** Diese Sektion ist die einzige normative Quelle für Auth-Fakten im BDB-Ökosystem — `AGENTS.md`, `bdbsaastraining/SKILL.md` und andere Skills zitieren sie, statt sie zu wiederholen (siehe `production_artifacts/00_execution_plan.md`, Finding B-4/Item B4).

+ > **Single Source of Truth.** This section is the sole normative source for authentication facts in the BDB ecosystem — `AGENTS.md`, `bdbsaastraining/SKILL.md`, and other skills reference it instead of repeating it.

- Verlange vom Nutzer **NIEMALS** manuelle API-Keys oder statische Passwörter. Das BDB-System nutzt automatisierte Zero-Trust-Handshakes:

+ **NEVER** ask the user for manual API keys or static passwords. The BDB system uses automated Zero-Trust handshakes:

- 1. **In Antigravity / Cursor IDE (Lokale Workstation):**

- * Das FastMCP-Gateway wird über `node bin/setup-workstation.mjs` (Browser-2FA via Authelia) automatisch angebunden.

- * Das aktive Token liegt lokal in `~/.gemini/antigravity-cli/mcp/bdb_remoteos_gateway/config.json`.

- * **Aktion:** Nutze direkt die bereitgestellten MCP-Tools (`remoteos_...`), ohne den Nutzer nach Verbindungsparametern zu fragen!

+ 1. **In Antigravity / Cursor IDE (Local Workstation):**

+ * The FastMCP Gateway is automatically wired via `node bin/setup-workstation.mjs` (Browser 2FA via Authelia).

+ * The active token lies locally in `~/.gemini/antigravity-cli/mcp/bdb_remoteos_gateway/config.json`.

+ * **Action:** Use the supplied MCP tools (`remoteos_...`) directly without asking the user for connection parameters!

- 2. **Auf dem Linux-Server via SSH:**

- * **Menschliche Admins:** Authentifizieren sich per `step ssh login <user>` (Authelia WebAuthn 2FA, 16h Ephemeral Certificates) und haben normales `sudo`.

- * **Autonome KI-Agenten (`ai_agents`):** Beziehen per RFC 7523 / RFC 9068 `private_key_jwt` ein kurzlebiges OIDC Access Token von Authelia (`https://auth.<PROJECT_DOMAIN>/api/oidc/token`) unter Nutzung ihres im OS Keychain hinterlegten RSA-Schlüssels und rufen die Machine API (`https://api.<PROJECT_DOMAIN>/tools/*`) mit `Authorization: Bearer <token>` auf.

- * **Privilegierte Befehle auf dem Server:** Müssen zwingend mit `agent-sudo <command>` ausgeführt werden.

+ 2. **On the Linux Server via SSH:**

+ * **Human Admins:** Authenticate via `step ssh login <user>` (Authelia WebAuthn 2FA, 16h ephemeral certificates) and have standard `sudo`.

+ * **Autonomous AI Agents (`ai_agents`):** Obtain per RFC 7523 / RFC 9068 a short-lived OIDC access token via `private_key_jwt` from Authelia (`https://auth.<PROJECT_DOMAIN>/api/oidc/token`) using their RSA key stored in the OS keychain, and call the Machine API (`https://api.<PROJECT_DOMAIN>/tools/*`) with `Authorization: Bearer <token>`.

+ * **Privileged Commands on the Server:** Must be executed with `agent-sudo <command>`.

---

- ## 🛠️ 3. Die FastMCP Werkzeugkiste (Tool-Übersicht)

+ ## 🛠️ 3. The FastMCP Toolkit (Tool Overview)

- Nutze für Cluster-Aufgaben direkt diese Tools:

+ Use these tools directly for cluster tasks:

- | Tool-Name | Zweck & Funktionsweise | Guardrail-Verhalten |

+ | Tool Name | Purpose & Function | Guardrail Behavior |

| :--- | :--- | :--- |

- | `remoteos_get_system_status` | Fragt den Live-Status aller Nodes, Incus-Container & Cloudflare-DNS ab. | Sofortige Ausführung |

- | `remoteos_create_instance` | Erstellt einen neuen Incus System-Container (Froxlor, WordPress, AI-Agent-Sandbox) mit automatischem DNS/Caddy Setup. | `staging1`: Sofort / `production`: 4-Augen-Freigabe |

- | `remoteos_manage_instance` | Lifecycle-Steuerung (start, stop, restart, delete). | `start/stop`: Sofort / `restart/delete`: 4-Augen-Freigabe |

- | `remoteos_add_route` | Richtet Caddy Reverse-Proxy Routen mit Authelia 2FA und Cloudflare DNS-Sync ein. | Sofortige Ausführung |

- | `remoteos_get_dns_blueprint` | Generiert RFC-konforme DNS-Pakete (A, MX, SPF, DKIM, DMARC) für Kunden-Domains. | Sofortige Ausführung |

- | `create_lldap_user` | Erstellt echte Accounts in LLDAP (`admins`, `users`, `ai_agents`) und verknüpft Agenten permanent mit ihrem `owner`. | Sofortige Ausführung (Background-Worker versendet Mails für Menschen) |

+ | `remoteos_get_system_status` | Queries the live status of all nodes, Incus containers, and Cloudflare DNS. | Immediate execution |

+ | `remoteos_create_instance` | Creates a new Incus system container (Froxlor, WordPress, AI-Agent sandbox) with automatic DNS/Caddy setup. | `staging1`: Immediate / `production`: four-eyes approval |

+ | `remoteos_manage_instance` | Lifecycle control (start, stop, restart, delete). | `start/stop`: Immediate / `restart/delete`: four-eyes approval |

+ | `remoteos_add_route` | Sets up Caddy reverse-proxy routes with Authelia 2FA and Cloudflare DNS sync. | Immediate execution |

+ | `remoteos_get_dns_blueprint` | Generates RFC-compliant DNS packets (A, MX, SPF, DKIM, DMARC) for customer domains. | Immediate execution |

+ | `create_lldap_user` | Creates real accounts in LLDAP (`admins`, `users`, `ai_agents`) and permanently links agents to their `owner`. | Immediate execution (background worker sends emails for humans) |

---

- ## 🛡️ 4. Das 4-Augen-Prinzip & `agent-sudo` (SSH-Ebene)

+ ## 🛡️ 4. The Four-Eyes Principle & `agent-sudo` (SSH Layer)

- Wenn ein Befehl oder ein MCP-Tool die Guardrails triggert:

+ When a command or MCP tool triggers the guardrails:

- 1. **Auto-Approve (Sichere Befehle):**

- * Befehle wie `ls`, `cat`, `grep`, `pwd`, `whoami` werden von `agent-sudo` in Millisekunden **automatisch genehmigt und als Root ausgeführt**.

- 2. **Manuelle Freigabe (Kritische Befehle):**

- * Befehle wie `docker`, `systemctl`, `rm`, `apt`, `incus` werden in die `queue.db` eingereiht.

- * Das Terminal blockiert ("*Warte auf Freigabe...*").

- * Der Besitzer (`owner`) erhält einen Push auf sein Dashboard: `https://gateway.<PROJECT_DOMAIN>/approvals`.

- * Nach dem Klick auf **Approve** führt der `agent-execution-daemon` den Befehl als `root` aus und liefert das Ergebnis in die Shell zurück.

+ 1. **Auto-Approve (Safe Commands):**

+ * Commands like `ls`, `cat`, `grep`, `pwd`, `whoami` are **automatically approved and executed as root** by `agent-sudo` in milliseconds.

+ 2. **Manual Approval (Critical Commands):**

+ * Commands like `docker`, `systemctl`, `rm`, `apt`, `incus` are queued into `queue.db`.

+ * The terminal blocks (*"Waiting for approval..."*).

+ * The owner (`owner`) receives a push to their dashboard: `https://gateway.<PROJECT_DOMAIN>/approvals`.

+ * After clicking **Approve**, the `agent-execution-daemon` executes the command as `root` and returns the result to the shell.

---

- ## 📋 5. Standard-Reaktionsmuster

+ ## 📋 5. Standard Response Patterns

- * **Wenn der Nutzer fragt:** *"Wie verbinde ich mich mit dem Cluster?"*

- $\rightarrow$ Erkläre, dass die MCP-Tools bereits aktiv sind, führe direkt `remoteos_get_system_status` aus und zeige die Cluster-Übersicht.

- * **Wenn der Nutzer fragt:** *"Lege einen neuen Agenten an"*

- $\rightarrow$ Rufe `create_lldap_user(username="agent-...", group="ai_agents", owner="<AKTUELLER_ADMIN>")` auf. Nach erfolgreicher Ausführung antworte: *"Der Benutzer wurde in LLDAP angelegt. Der Background-Worker versendet nun automatisch die Setup-E-Mails."* Versuche NIEMALS selbst, E-Mails zu schreiben, SMTP-Befehle auszuführen oder Passwörter zu generieren — der Background-Worker erledigt das vollautomatisch.

- * **Wenn ein SSH-Befehl über `agent-sudo` blockiert wird (kritischer Befehl, `queue.db`):**

- $\rightarrow$ Informiere den Nutzer: *"Diese Aktion erfordert eine 4-Augen-Freigabe. Bitte bestätige sie im Approval-Dashboard."*

- * **Wenn ein FastMCP-Tool-Aufruf (z. B. `incus_create_instance`, `incus_manage_instance`) mit `{"status": "queued", ...}` blockiert wird, weil du der LDAP-Gruppe `ai_agents` angehörst:**

- $\rightarrow$ Mache KEINEN Retry und versuche nicht, den Fehler selbst zu beheben. Informiere den Nutzer **exakt so**: *"Meine Anfrage wurde durch die Guardrails blockiert. Bitte gib die Anfrage hier frei: [https://gateway.<PROJECT_DOMAIN>/approvals](https://gateway.<PROJECT_DOMAIN>/approvals)"*

- * **Wenn der Nutzer fragt:** *"Zeig mir ausstehende Anfragen"* oder *"Checke die Freigaben"*

- $\rightarrow$ **`get_pending_approvals` wurde stillgelegt (A9, 2026-09-06)** — ein Maschinen-Tool, das die Freigabe-Queue lesen kann, untergräbt das Vier-Augen-Prinzip strukturell. Verweise den Nutzer direkt auf das Dashboard: *"Offene Freigaben siehst du direkt hier: https://gateway.\<PROJECT_DOMAIN\>/approvals"*

+ * **When the user asks:** *"How do I connect to the cluster?"*

+ $\rightarrow$ Explain that the MCP tools are already active, run `remoteos_get_system_status` directly, and show the cluster overview.

+ * **When the user asks:** *"Create a new agent"*

+ $\rightarrow$ Call `create_lldap_user(username="agent-...", group="ai_agents", owner="<CURRENT_ADMIN>")`. After successful execution, reply: *"The user has been created in LLDAP. The background worker now sends the setup emails automatically."* **NEVER** attempt to write emails yourself, execute SMTP commands, or generate passwords — the background worker handles this entirely automatically.

+ * **When an SSH command via `agent-sudo` is blocked (critical command, `queue.db`):**

+ $\rightarrow$ Inform the user: *"This action requires four-eyes approval. Please confirm it in the Approval Dashboard."*

+ * **When a FastMCP tool call (e.g. `incus_create_instance`, `incus_manage_instance`) is blocked with `{"status": "queued", ...}` because you belong to the LDAP group `ai_agents`:**

+ $\rightarrow$ Do NOT retry and do not attempt to fix the error yourself. Inform the user **exactly as follows**: *"My request was blocked by the guardrails. Please approve it here: [https://gateway.<PROJECT_DOMAIN>/approvals](https://gateway.<PROJECT_DOMAIN>/approvals)"*

+ * **When the user asks:** *"Show me pending requests"* or *"Check the approvals"*

+ $\rightarrow$ **`get_pending_approvals` was decommissioned (A9, 2026-09-06)** — a machine tool that could read the approval queue would structurally undermine the four-eyes principle. Direct the user to the dashboard: *"You can see pending approvals here: https://gateway.\<PROJECT_DOMAIN\>/approvals"*