From 7289ebb73eee448664b2a0d15c10e0368cdd1aa3 Mon Sep 17 00:00:00 2001 From: Wmj Ismail Date: Sun, 9 Aug 2026 11:29:27 +0800 Subject: [PATCH] Add AI agent onboarding guide Covers: infrastructure map, Hermes config, Bitwarden access, Gitea tokens & repos, 26 LLM providers, SSH keys, Telegram bot, n8n automation, key files, quick-start workflows, and common issues troubleshooting. --- ai-onboarding-guide.md | 392 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 392 insertions(+) create mode 100644 ai-onboarding-guide.md diff --git a/ai-onboarding-guide.md b/ai-onboarding-guide.md new file mode 100644 index 0000000..e5b4c95 --- /dev/null +++ b/ai-onboarding-guide.md @@ -0,0 +1,392 @@ +# AI Agent Onboarding Guide — FalahOS + +> **Purpose:** This document is a full onboarding prompt for any new AI agent (Hermes, Claude Code, OpenCode, Codex, Pi, OpenClaude, etc.) joining the FalahOS infrastructure. It covers everything needed to operate autonomously: where credentials live, how to access infrastructure, what LLM providers are available, Git/Gitea setup, SSH, and key workflows. + +--- + +## Table of Contents + +1. [Infrastructure Overview](#1-infrastructure-overview) +2. [Hermes Agent](#2-hermes-agent) +3. [Bitwarden (Password Manager)](#3-bitwarden-password-manager) +4. [Gitea (Git)](#4-gitea-git) +5. [LLM Providers & API Keys](#5-llm-providers--api-keys) +6. [SSH Access & Keys](#6-ssh-access--keys) +7. [GitHub Access](#7-github-access) +8. [Telegram Bot](#8-telegram-bot) +9. [n8n Automation](#9-n8n-automation) +10. [Key Files & Locations](#10-key-files--locations) +11. [Quick-Start Workflows](#11-quick-start-workflows) + +--- + +## 1. Infrastructure Overview + +### Machines + +| Host | IP / Hostname | Role | Access | +|---|---|---|---| +| **MacBook Air** (this) | localhost | Primary agent host: Hermes, Pi, JCode, CrewAI, Graphify, Fincept | Direct terminal | +| **Mac Mini** | `192.168.0.10` | Odysseus, OpenClaw, HeadlessX, Bridge (port 5001) | SSH via local | +| **MacBook Pro** | `192.168.0.27` | OpenHands, OMP gateway, Bridge (port 5002) | SSH via local | +| **Synology DSM7** | `192.168.0.30` | OpenClaude Docker (port 4501) | SSH via local | +| **Contabo VPS** | `13.140.161.244` | Swarm leader: Traefik, Mautic, Ghost (~6k subs), Listmonk, Garage S3, Termix | SSH via SSH key | +| **cPanel** | `webhosting2018.is.cc` | Legacy hosting: PHP sites, email | Password auth | + +### Network Notes + +- All machines are on the same local LAN (192.168.0.x) +- `*.falahos.my` wildcard DNS → Contabo VPS `13.140.161.244` +- Colima (Docker on Mac) auto-forwards container ports through SSH multiplexer — these bypass macOS Application Firewall +- Mac Mini OpenClaw gateway is loopback-only, port 18789 — needs SSH tunnel to reach from other machines +- Contabo VPS has intermittent SSH timeouts — retry if fails + +--- + +## 2. Hermes Agent + +**Version:** v0.20.0 (2026.8.3) +**Config:** `~/.hermes/config.yaml` +**Profile:** default (at `~/.hermes/`) + +### Default Model +``` +model: + default: deepseek-v4-flash + provider: opencode + base_url: https://opencode.ai/zen/v1 +``` + +### Key Config Sections +- **MCP Servers** — 15 servers (see `wmj/agent-configs/mcp-integration-guide.md`) +- **LLM Providers** — 26 configured providers +- **Custom Provider:** `omp` at `http://192.168.0.27:20128` +- **Model Aliases:** `omp` → `minimax-m3` +- **Fallback Chain:** `opencode-zen` → `openai-codex` → `openrouter` → `anthropic` + +### Useful Hermes Commands + +```bash +hermes mcp list # Show all MCP servers + status +hermes config list # Show config values +hermes model list # List available models +hermes tools # List available tools +hermes version # Version + update check +hermes gateway restart # Restart the gateway (after config changes) +``` + +### Telegram Connection +- Bot token: `/tmp/.telegram_token` — NEVER put in env vars +- Bot username: `@falahos_bot` + +--- + +## 3. Bitwarden (Password Manager) + +| Property | Value | +|---|---| +| **Server URL** | `https://bitwarden.falahos.my` | +| **Email** | `wanjauhari@gmail.com` | +| **Master Password** | `Abedib@99123` | +| **CLI Binary** | `~/.local/bin/bw` | + +### CLI Usage + +```bash +# Check status +bw status + +# If locked, unlock with session +BW_PASSWORD="Abedib@99123" bw unlock +# → exports BW_SESSION= + +# Search items (once unlocked) +bw list items --search "search_term" | jq '.[] | {name, login}' + +# Common search terms to use: +# - "openai" / "anthropic" / "gemini" — LLM API keys +# - "contabo" / "vps" — server credentials +# - "gitea" / "git" — Gitea tokens +# - "domain" / "falahos" — domain registrar access +# - "cpanel" / "hosting" — hosting credentials +# - "ghost" — CMS admin credentials +# - "n8n" — automation credentials +# - "telegram" / "bot" — bot tokens +``` + +### What's Stored in Bitwarden + +Bitwarden is the canonical source of truth for ALL secrets: +- LLM provider API keys (OpenAI, Anthropic, Google, Alibaba, etc.) +- Server SSH passwords & keys +- Domain registrar credentials +- Email account passwords (SMTP/IMAP) +- CMS admin logins (Ghost, WordPress) +- Social media account credentials +- Cloudflare API tokens +- Payment processor keys (Stripe, Gumroad) +- n8n encryption keys + +**Rule:** NEVER hardcode secrets in config files or scripts. Always fetch from Bitwarden via CLI at startup or session-initialization time. + +--- + +## 4. Gitea (Git) + +| Property | Value | +|---|---| +| **URL** | `https://git.falahos.my` | +| **Primary Org** | `falah-os` | +| **User** | `wmj` (admin) | +| **Auth Tokens** | Stored in `~/.netrc_quran` | + +### Gitea Tokens (in ~/.netrc_quran) + +| Token Username | Scope | Use Case | +|---|---|---| +| `anyuser` | Pull-only | Read/clone public repos (agent defaults) | +| `wmj` | Full access | Push to repos, PRs, issues (password: `Abedib@99`) | +| `falah-os` | Full access | Org-level pushes | +| `falah` | Limited | Specific repo access | +| `hermes-bot` | Bot operations | Automated git ops | + +### Gitea Token Format + +The `.netrc_quran` file contains Gitea tokens as HTTPS URLs: +``` +https://USERNAME:TOKEN@git.falahos.my +``` + +Use these directly as git remote URLs for push access. + +### Key Repositories + +| Repo | Description | +|---|---| +| `falah-os/nur-muslim-companion` | Nur — Muslim Companion PWA (Svelte) — Phase 1 | +| `falah-os/nur-muslim-companion-v2` | Nur v2 — expanded features | +| `wmj/agent-configs` | Agent configs, provider setups, onboarding docs | +| `wmj/digital-khalifah` | Digital Khalifah content | +| `wmj/digital-mujtahid` | Digital Mujtahid content | +| `wmj/digital-waqif` | Digital Waqif content | +| `wmj/kitab-kuning-covers` | 3D book cover assets | +| `hermes-macbookair/nur-falah` | Nur Falah — Muslim Companion PWA (latest) | + +### Git Global Config +``` +user.name = Wmj Ismail +user.email = wmj@falahos.my +credential helper → ~/.netrc_quran (via Git credential store) +``` + +--- + +## 5. LLM Providers & API Keys + +### Provider Matrix + +| Provider | Models Available | How to Access Keys | +|---|---|---| +| **opencode-zen** | deepseek-v4-pro/flash, gpt-5.x, claude-opus-4, gemini-3, qwen-3.7, kimi-k2, minimax-m3 | Free tier available — no key needed for most models | +| **opencode-go** | minimax-m3/m2.7, kimi-k3/k2.7, glm-5.2, deepseek-v4, qwen-3.x, mimo-v2, hy3, gpt-5.6, grok-4.5 | Free tier | +| **alibaba** | qwen-3.x family, deepseek-v4, kimi-k2.5, glm-5, minimax-m2.5 | API key in Bitwarden | +| **copilot** | gpt-5.x, claude-sonnet-4.6/5, gemini-3.x | Key in Bitwarden | +| **openai-api** | gpt-5.6 sol/terra/luna, gpt-5.5/5.4, gpt-5-codex | Key in Bitwarden | +| **openai-codex** | gpt-5.6, gpt-5.5, gpt-5.4-mini, gpt-5.3-codex | Key in Bitwarden | +| **anthropic** | claude-fable-5, claude-sonnet-5, claude-opus-4.x, claude-haiku | Key in Bitwarden | +| **gemini** | gemini-3.5-flash, gemini-2.5-pro, gemini-3.x | Key in Bitwarden | +| **openrouter** | deepseek, claude, openai, google (fallback) | Key in config (empty) | + +### Default Fallback Chain + +```yaml +opencode-zen → openai-codex → openrouter → anthropic +``` + +### Adding a New LLM Key + +1. **Open Hermes config** `~/.hermes/config.yaml` +2. **Find the provider section** (e.g., `openai:`, `anthropic:`) +3. **Set the API key** — either directly in config or via env var +4. **Verify** with `hermes model list` + +**Key storage policy:** +- Keys go in Bitwarden as the canonical source +- For Hermes config, prefer env vars over inline (but the config supports inline for active providers) +- The `api_key: ''` entries in config mean the key comes from env or is unused + +--- + +## 6. SSH Access & Keys + +### SSH Key Pair + +| Key | Path | Purpose | +|---|---|---| +| **ED25519** | `~/.ssh/id_ed25519` (public: `~/.ssh/id_ed25519.pub`) | Primary auth key for all servers | +| **RSA** | `~/.ssh/id_rsa` | Fallback/compatibility | + +### Hosts Accessed via SSH + +| Host | User | Auth Method | Notes | +|---|---|---|---| +| `13.140.161.244` (Contabo VPS) | `root` | SSH key + password (in Bitwarden) | Intermittent timeouts — retry | +| `192.168.0.10` (Mac Mini) | `wanjauhari24` or delegated | SSH key | LAN | +| `192.168.0.27` (MacBook Pro) | `wanjauhari24` or system user | SSH key | LAN | +| `192.168.0.30` (Synology DSM7) | Admin user | SSH key | LAN; Docker containers via SSH then docker exec | +| `colima` (via `~/.colima/ssh_config`) | Lima VM user | SSH key via `ssh -F ~/.colima/ssh_config colima` | Colima Docker VM | + +### Colima SSH +```bash +ssh -F ~/.colima/ssh_config colima +# Docker containers inside Colima auto-forward ports to 127.0.0.1 +``` + +### Contabo VPS (Troubleshooting) +- Connection timeouts are common — retry 2-3 times with `-o ConnectTimeout=10` +- The VPS runs: Docker Swarm (Traefik, Mautic, Ghost, Listmonk, Garage S3) +- Termix web terminal at `termix.falahos.my` (user: `falahosadmin` / pass: `FalahOSAdmin2026`) + +--- + +## 7. GitHub Access + +### GitHub CLI (gh) +```bash +gh auth status # Check current auth +gh repo list # List repos (read-only) +gh pr list # List PRs +``` + +GitHub auth is handled via the `gh` CLI credential helper registered in `~/.gitconfig`: +``` +[credential "https://github.com"] + helper = !/opt/homebrew/bin/gh auth git-credential +``` + +**Note:** GitHub access is primarily read-only for FalahOS. All active development repos are on self-hosted Gitea (`git.falahos.my`). + +--- + +## 8. Telegram Bot + +| Property | Value | +|---|---| +| **Bot Token Location** | `/tmp/.telegram_token` (file) | +| **Bot Username** | `@falahos_bot` | +| **Token Value** | Read from file: `cat /tmp/.telegram_token` | + +### Rules +- **NEVER** put the bot token in environment variables or shell history +- Read it from `/tmp/.telegram_token` when needed +- The token starts with `8750645268:` + +### Using the Bot API + +```python +import urllib.request, json +token = open("/tmp/.telegram_token").read().strip() +url = f"https://api.telegram.org/bot{token}/sendMessage" +data = json.dumps({"chat_id": "CHAT_ID", "text": "Hello"}).encode() +urllib.request.urlopen(urllib.request.Request(url, data=data, headers={"Content-Type": "application/json"})) +``` + +--- + +## 9. n8n Automation + +| Property | Value | +|---|---| +| **URL** | `http://13.140.161.244:5678` | +| **Encryption Key** | `falahos-n8n-key-2026` | + +### Notes +- Self-hosted n8n on Contabo VPS (Docker) +- Used for automation workflows, not for Publora or Composio (those are direct) +- Warm up before broadcast — first request may be slow + +--- + +## 10. Key Files & Locations + +| File | Purpose | +|---|---| +| `~/.hermes/config.yaml` | Main Hermes agent configuration | +| `~/.netrc_quran` | Gitea tokens (HTTPS URLs with credentials) | +| `~/.ssh/id_ed25519` | SSH private key | +| `~/.ssh/config` | SSH config (includes colima) | +| `~/.gitconfig` | Git user config + credential helpers | +| `~/.hermes/skills/` | All available skills (loaded per-session) | +| `~/.hermes/cron/` | Scheduled cron jobs | +| `~/.hermes/plans/` | Saved plans | +| `/tmp/.telegram_token` | Telegram bot token | +| `~/.openclaw/openclaw.json` | OpenClaw gateway config (port 18789, token inside) | +| `~/.local/bin/bw` | Bitwarden CLI | + +--- + +## 11. Quick-Start Workflows + +### 🆕 First-Time Setup Checklist + +- [ ] Confirm Hermes is running: `hermes mcp list` (all 15 should be ✓ enabled) +- [ ] Confirm Gitea access: `git ls-remote https://git.falahos.my/wmj/agent-configs.git` +- [ ] Confirm Bitwarden access: `bw status` (if locked, unlock with password) +- [ ] Confirm SSH access: `ssh -o ConnectTimeout=5 root@13.140.161.244 "hostname"` +- [ ] Check Telegram connection: verify bot responds +- [ ] Read the MCP integration guide: `wmj/agent-configs/mcp-integration-guide.md` + +### 🔍 Finding Credentials + +When you need a credential: + +1. **Check memory** first (if previously saved) +2. **Check Bitwarden** via CLI: `bw list items --search "keyword"` +3. **Check config files** in `~/.hermes/`, `~/.ssh/`, `~/.netrc*` +4. **Check `/tmp/`** for transient secrets +5. **Ask the user** as last resort + +### 🚀 Preferred Model Routing + +| Task | Recommended Model / Provider | +|---|---| +| General chat, quick tasks | `deepseek-v4-flash` (opencode-zen) | +| Complex coding | `gpt-5.3-codex` (openai-codex) or `claude-sonnet-5` (anthropic) | +| Heavy reasoning | `deepseek-v4-pro` (opencode-zen) | +| Content creation | `gpt-5.5` or `gpt-5.6-terra` (openai-api) | +| Free / experimental | Free-tier models on opencode-zen: `deepseek-v4-flash-free`, `mimo-v2.5-free` | +| Cheap inference | `qwen3.6-flash` or `gemini-3.5-flash` | +| Vision tasks | `qwen-vl-max`, `gemini-3.5-flash` | +| Image generation | `qwen-image-3.0-pro` (alibaba) | + +### 🐛 Common Issues & Fixes + +| Issue | Fix | +|---|---| +| `hermes mcp test` fails | Known bug — use `hermes mcp list` + curl instead | +| Gitea API times out | API often slow; use `git clone` directly instead | +| Contabo SSH timeout | Retry 2-3x with short timeout; check termix.falahos.my | +| Bitwarden locked | `bw unlock --passwordenv BW_PASSWORD` or prompt user | +| APFS dataless purge (scripts vanish) | Check `ls -lO` for 'dataless' flag; restore from session history | + +--- + +## Infrastructure Quick Reference + +``` +Services Summary: +┌──────────────────────┬───────────────┬──────────────────┐ +│ Service │ URL │ Host │ +├──────────────────────┼───────────────┼──────────────────┤ +│ Gitea │ git.falahos.my│ Contabo │ +│ Ghost CMS │ ghost.falahos.my│ Contabo (Docker)│ +│ Termix │ termix.falahos.my│ Contabo (Docker)│ +│ Bitwarden │ bitwarden.falahos.my│ Contabo │ +│ n8n │ contabo:5678 │ Contabo (Docker) │ +│ Partners Landing │ partners.falahos.my│ Netlify │ +│ Mautic │ ma.falahos.my │ Contabo (Docker) │ +│ Listmonk │ ml.falahos.my │ Contabo (Docker) │ +└──────────────────────┴───────────────┴──────────────────┘ +``` + +> **Remember:** When in doubt about a credential, ask the user. Better to ask than to guess wrong and break something.