Overview

Helios is observability infrastructure for Telegram. Authorized clients monitor presence, activity, identity, stories, NFT usernames, photos, reactions, and shared-chat messages of explicitly-added targets — while the platform stays absolutely invisible to those targets.

This site is the operator and developer documentation. The canonical instructions for any contributor (human or AI) live in CLAUDE.md at the repository root.

The four invariants

Everything else in the project is in service of these:

1. Stealth is sacred. The userbot cluster never performs any action a target could perceive. Enforced in code, CI, and tests.
2. Multi-tenant by construction. Every row, every query, every search hit is scoped to one client; cross-tenant leakage is a P0 incident.
3. One userbot, many subscribers. Capture once, fan out N times via Redis Streams — scaling is linear in distinct targets, not in clients.
4. Owner-tunable at runtime. Anything that could conceivably differ between environments, tiers, clients or targets is a parameter, editable from the admin panel without a restart.

Pick a starting point

• Architecture — three layers, the data flow, the invariants. 15 minutes.
• Onboarding — first deploy walkthrough.
• Runbook — common incidents and the first three things to check.
• Stealth thesis — why the userbot fleet is read-only by construction.

Source of truth hierarchy

When two documents disagree, follow this order:

1. The code itself — core/policies/*, core/settings/parameters.py, migrations under infrastructure/db/migrations/.
2. CLAUDE.md — the project's operating manual.
3. ADRs — load-bearing decisions.
4. This documentation site — written for humans, may lag the code by a commit or two.