merox-agent

Intelligent infrastructure agent for the merox.dev homelab:

• Oracle Cloud server — Docker services, system health
• Kubernetes cluster — Talos OS, FluxCD GitOps, Longhorn
• Website — merox.dev

Built with Claude Agent SDK — uses your Claude Code account, no separate API key needed.

Interfaces: Telegram bot (phone) + CLI client (laptop).

---

Disaster recovery — rebuild from zero

Use this if you lose the Oracle server or get a new laptop.

1. New Oracle Cloud server

# 1. Provision Ubuntu 22.04+ VM on Oracle Cloud (Free Tier works)
#    Open port 8765 in the security list (or keep it Tailscale-only)

# 2. Install Tailscale and connect to your network
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
# Note the Tailscale IP: tailscale ip -4

# 3. Install Python 3.11+
sudo apt update && sudo apt install -y python3 python3-venv python3-pip git

# 4. Install Node.js and Claude Code CLI
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
sudo npm install -g @anthropic-ai/claude-code

# 5. Authenticate Claude Code (follow the browser OAuth prompt)
claude

# 6. Clone the agent repo
sudo git clone https://github.com/meroxdotdev/merox-agent /srv/merox-agent
cd /srv/merox-agent

# 7. Configure
sudo cp .env.example .env
sudo nano .env
# Fill in: SERVER_TS_IP, INFRA_REPO, WEBSITE_REPO, TELEGRAM_BOT_TOKEN, TELEGRAM_USER_ID

# 8. Install (creates virtualenv, systemd service, Claude permissions)
sudo bash install.sh

That's it. The agent is running and the Telegram bot is active.

Verify:

systemctl status merox-agent
journalctl -u merox-agent -f

---

2. New laptop (connect to existing server)

# 1. Install Tailscale and connect
# 2. Install Python deps
pip install httpx

# 3. Clone repo (or just grab client.py)
git clone https://github.com/meroxdotdev/merox-agent
cd merox-agent

# 4. Configure server URL
echo "AGENT_SERVER_URL=http://<SERVER_TAILSCALE_IP>:8765" > .env

# 5. Run
python3 client.py

Or just use the Telegram bot — no setup needed on the laptop at all.

---

3. What lives where

What	Where	Backed up?
Agent code	GitHub (this repo)	✅
Infra repo (k8s manifests)	GitHub (meroxdotdev/infrastructure)	✅
Website repo	GitHub (meroxdotdev/merox)	✅
Server .env (Telegram token, IPs)	Only on server	⚠️ Save it somewhere safe
Kubernetes secrets (SOPS)	Git-encrypted in infra repo	✅ (need AGE key)
AGE encryption key	/srv/kubernetes/infrastructure/age.key	⚠️ Back this up — losing it = losing all secrets

The one thing you must back up manually: the AGE key at age.key. Everything else is in git.

---

Usage

Telegram (recommended for phone)

Message @meroxagentbot — ask anything about your infra.

• /clear — reset conversation

CLI (laptop)

python3 client.py                        # interactive
python3 client.py "what pods are down?"  # one-shot

Examples

what is the status of the cluster?
which pods are not running?
show me traefik logs
how much disk is left on the server?
what changed in the infra repo recently?
reconcile flux-system

---

Architecture

Phone/Laptop
    │
    ├── Telegram bot ──────────────────────┐
    └── client.py ─── HTTP (Tailscale) ───►│
                                           │ service.py (FastAPI)
                                           │   └── Claude Agent SDK
                                           │         └── Claude Code CLI
                                           │               └── Bash tool
                                           │                     ├── kubectl
                                           │                     ├── talosctl
                                           │                     ├── flux
                                           │                     └── docker
                                    Oracle Cloud Server

Project structure

merox-agent/
├── service.py          # HTTP server + Telegram bot
├── client.py           # CLI client (laptop)
├── agent.py            # standalone agent (needs ANTHROPIC_API_KEY)
├── config.py           # configuration from env vars
├── prompt.py           # system prompt with infra context
├── tools/
│   ├── kubernetes.py   # kubectl, flux, talosctl (used by agent.py)
│   ├── server.py       # docker, systemctl, shell (used by agent.py)
│   └── git_tools.py    # git operations (used by agent.py)
├── install.sh          # server setup script
├── merox-agent.service # systemd unit (generated by install.sh)
├── requirements.txt
└── .env.example