agent-configs/ai-onboarding-guide.md

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
2. Hermes Agent
3. Bitwarden (Password Manager)
4. Gitea (Git)
5. LLM Providers & API Keys
6. SSH Access & Keys
7. GitHub Access
8. Telegram Bot
9. n8n Automation
10. Key Files & Locations
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

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

# Check status
bw status

# If locked, unlock with session
BW_PASSWORD="Abedib@99123" bw unlock
# → exports BW_SESSION=<session_token>

# 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

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

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)

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

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.