Docs

Aromba — Overview

Aromba is an open-source caretaker for your server (later: your Mac). It runs small maintenance jobs called chores, reports to you in Telegram, and can answer questions and fix things when you ask. It works while you are away and helps while you are there.

One-line pitch: “Your server takes care of itself. You get a receipt in the morning.”

Who it is for

1. Vibe coders — deployed with Claude Code, don’t know sysadmin. Aromba is the admin they don’t have.
2. Developers — run apps on a VPS, want disk, logs, backups and updates handled without thinking.
3. Power users — want to plug in their own chores and their own AI model.

Public positioning is dev / vibe-coder only. Other audiences arrive later via optional skills (see below).

Principles

1. Trust before power. Aromba never deletes user data. Regenerable junk is cleaned; everything else goes to quarantine for 30 days with one-tap restore.
2. Three colors. Every chore is green (runs itself), yellow (quarantines, never deletes) or red (asks in Telegram first). Anything written by the AI is red.
3. Free until you ask. Chores, watchers and the morning receipt use no AI. AI is called only when the user asks a question or a watcher finds something abnormal.
4. The receipt is the product. Every action is logged in one line. The morning receipt is the log, readable by a human.
5. One chat, one server. The bot answers one Telegram chat only. Everyone else is ignored.
6. Kill switch always works. /panic stops everything except the chat itself.
7. Small core, skills grow it. The base install is minimal; chores, capabilities and integrations are skills with a declared weight and permissions. Anyone can add one; the core team promotes it from red to green.
8. Nearly invisible. Aromba at idle uses under 1% of a core and under 50 MB; chores run at low priority and pause when the server is busy. We show our own footprint on the dashboard.
9. Safe for people who don’t read. A separate Warden process holds all power; the Worker can only ask. Rights are earned over a week and lost on the first strange move. Nothing here depends on the user understanding it (05-security.md).

What Aromba is not

• Not a general AI agent framework. The assistant acts only through chores and approved commands.
• Not a second control plane. The dashboard edits settings and chores under the same approval and PIN rules; red actions still confirm in Telegram.
• Not a cloud that runs your server. Chores, watchers and the assistant run on the user’s machine. Aromba’s servers receive only what the bot already sends: status, receipts, health numbers. Never file contents, never keys.

Website and dashboard — aro.mba

One domain, two halves:

• Website (public): landing, install command, docs, changelog. Static.
• Dashboard (after login with Telegram): one page per connected server. Shows: what chores ran and what is scheduled, device health over time (disk, memory, CPU, uptime, failed logins, pending updates), the receipt history, quarantine with restore, and a live activity log. Dashboard data is the same stream the Telegram bot receives, stored per user.

Login happens in the chat: the page shows a code, the bot asks whether it is you, and the same identity connects bot and dashboard with no password and no phone number. Details in 08-dashboard.md.

Phases

Each phase is a public release. Details in 07-roadmap.md.

Skills

The base install is the lightest possible version: engine, bot, assistant with its core tools, and the system skill. Everything else is a skill from the catalog at aro.mba/skills: chore sets (docker, postgres, nextjs…), capabilities (voice, web docs, off-server backups), integrations (GitHub, Cloudflare, Vercel), and knowledge (runbooks that only add text for the assistant). Every skill declares its weight and its permissions, both shown before install. The first scan suggests skills for what it found; the assistant can propose one; the user enables it with a tap. Official skills are signed; community skills run red until reviewed. The skill mechanism exists from phase 2. Skills for other audiences are not mentioned in public materials until phase 5.

Naming

• Product and repo: Aromba. Domain: aro.mba (website + dashboard).
• Bot: @aroomba_bot.
• Internal name of the AI assistant inside the bot: just “Aromba”. No second character.

Documents