GeezerVison

Security-first Telegram userbot ecosystem built on GoyGram with Linux namespace isolation.

The Hotaru Project maintains an open-source Telegram userbot runtime focused on process containment, explicit capability privileges, and modular extension development.

Legacy userbot engines execute third-party code in the same interpreter as the core Telegram client, exposing plaintext session strings and encryption keys to untrusted scripts. Hotaru solves this by decoupling the core process from modular workers via Linux namespaces and restricted IPC channels.

Telegram Network
       │
       ▼ (MTProto / GoyGram 0.8.28)
┌──────────────────────────────────────────────────────────┐
│                      Hotaru Core                         │
│  - Multi-Account Supervisor                              │
│  - Encrypted Master Vault (sanctuary/hotaru.vault)       │
│  - Shield Rate Limiter & FloodWait Guard                 │
│  - Singularity Mini App Engine (port 8787)               │
└──────────────────────────┬───────────────────────────────┘
                           │ IPC Gate (UNIX sockets)
       ┌───────────────────┼───────────────────┐
       ▼                   ▼                   ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ Worker 1     │    │ Worker 2     │    │ Worker 3     │
│ CLONE_NEWNS  │    │ CLONE_NEWNS  │    │ CLONE_NEWNS  │
│ CLONE_NEWNET │    │ CLONE_NEWNET │    │ CLONE_NEWNET │
│ nobody:65534 │    │ nobody:65534 │    │ nobody:65534 │
│ mod_a.hmod   │    │ mod_b.hmod   │    │ mod_c.hmod   │
└──────────────┘    └──────────────┘    └──────────────┘

1. Linux Namespace Containment: Modules (.hmod) execute inside unprivileged worker processes isolated with CLONE_NEWNS, CLONE_NEWIPC, CLONE_NEWUTS, and CLONE_NEWNET. Workers run as user nobody (uid: 65534) on an ephemeral tmpfs root.

2. Capability Security Model: Modules declare requested permissions explicitly in their manifest:

   • mt: Access to Telegram MTProto RPC methods on ctx.
   • state: Scoped SQLite database persistence isolated per module ID.
   • net: Outbound HTTP traffic routed through a security proxy. If omitted, the network namespace blocks outbound sockets at the kernel level.
   • files: Temporary scratchpad filesystem inside the sandbox.

3. Master Encryption Vault: Session strings, database entries, and authorization keys are stored on disk encrypted with AES-GCM in sanctuary/hotaru.vault. Master secrets are never passed into module worker environments.

4. Zero Comments Policy: All production code, core modules, and .hmod files maintain documentation integrity without inline comment bloat.

Run the interactive installer on any supported Linux system:

curl -fsSL https://raw.githubusercontent.com/HotaruProject/Hotaru/main/install.sh | bash

The installer verifies prerequisites, prompts for Telegram API credentials, and configures your preferred runtime (systemd service, Docker Compose, or Proxmox LXC).

Modules are loaded live in Telegram without restarting the core process:

1. Save your script with a .hmod extension. The HOTARU = { ... } manifest must be the very first statement.
2. Send the file document to any chat or Saved Messages.
3. Reply to the document with .ld.
4. Hotaru verifies the AST, checks requested capabilities, spawns an isolated worker, and displays an activation card.

Explore all 292 extended MTProto methods and code patterns in the Developer Documentation.

We maintain an official instruction file (SKILL.md) for AI agents (Antigravity, Cursor, Claude Code, ChatGPT) to write correct, sandboxed .hmod modules:

• Download: hotaruproject.github.io/skill/SKILL.md

• Telegram Community: t.me/HotaruProject
• Security Vulnerability Reports: See SECURITY.md

Software published by the Hotaru Project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for details.