Zero is a self-hosted Telegram AI companion in an alpha state. The main branch contains a Telegram user-session listener, an owner-only management bot, a local web administration panel, a terminal administration interface, SQLite-backed state, provider routing, controlled web search, memory services, and an optional OfficeCLI workflow.
Repository: https://github.com/mhrsdev/Zero-Agent.git
Alpha status: This README describes the current
main/0.1.0-alpharelease line. It is not a production-readiness statement.IMPLEMENTEDmeans source code exists;VERIFIED LOCALLYmeans the corresponding tests or local smoke command passed;LIVE E2E VERIFIEDis reserved for a real external-account or provider run. This audit did not perform live Telegram or paid-provider E2E verification.
- Telegram user-session listener using Telethon, restricted by configured group allowlists.
- Owner-only Telegram management bot using aiogram.
- Local
aiohttpadministration panel with health, authentication, setup, and operational views. - Curses-style TUI with status, doctor, groups, backup, logs, and setup panels.
- SQLite storage and the current Memory V3 service, with migration tooling from older V1 data.
- Legacy runtime provider routing for Gemini and OpenRouter, including key pools, cooldowns, quotas, retries, and fallback.
- A separate Provider Registry component with symbolic secret references, fallback chains, rate limiting, health, and usage accounting.
- Google Grounding-backed live search through configured official external APIs.
- Legacy/internal SearXNG code remains in the tree but is disabled and is not a public Zero feature.
- Optional OfficeCLI document workflows for DOCX, XLSX, and PPTX, guarded by explicit commands, quotas, validation, isolated workspaces, rendering, and delivery state.
Feature status is intentionally conservative. Presence of a module or test is not treated as proof of a live external integration.
Telegram user session ──▶ run_listener.py ──▶ ZeroBrain ──▶ SQLite / Memory V3
│ ├── IndependentRouter
│ ├── Google Grounding / web pipeline
│ └── optional OfficeCLI workers
Telegram management bot ──▶ run_panel.py ──▶ PanelAPI ──▶ local aiohttp panel
python -m zero tui ──▶ read-only operational panels
The default composition roots instantiate IndependentRouter(config) directly. The newer zero.providers.ProviderRegistry is optional in IndependentRouter; it is tested and usable, but it is not the registry-backed default composition for the listener and panel in this commit.
run_listener.py creates a Telethon TelegramClient from the legacy runtime configuration. It requires a Telegram API ID, API hash, and authorized session file. Messages are processed only for configured allowed groups. A private message can be observed for permission and Office command handling, but the listener is not a general public bot account.
Status: IMPLEMENTED; local contract tests pass; LIVE E2E VERIFIED: no.
run_panel.py creates an aiogram Bot from a protected BOT_TOKEN=... file. Management commands are owner-only and private-chat restricted. The panel process also serves the local HTTP panel.
Status: IMPLEMENTED; local panel and authentication tests pass; LIVE E2E VERIFIED: no.
The canonical setup schema accepts disabled, bot, user_session, and hybrid and validates the required symbolic secret references. Same-commit tests cover that contract and Office Telegram bridge behavior. The public listener and panel composition roots still run as two separate legacy processes; this commit does not provide a single canonical mode switch that replaces both processes.
Status: IMPLEMENTED as configuration and adapter contracts; VERIFIED LOCALLY by tests; not a claim of unified live deployment.
The default runtime path is zero.router.IndependentRouter:
- Gemini is used for Google Grounding search calls.
- Gemini and OpenRouter are configured in the legacy YAML runtime config.
- Provider key pools expose redacted key IDs, quota state, cooldowns, retries, and fallback metadata.
- Secrets are loaded from protected files and are not intended to be committed.
zero.providers.ProviderRegistry is a separate, implemented component. It accepts ProviderProfile objects and symbolic secret_ref values, and its routing, fallback, redaction, health, cost, and rate-limit behavior is locally tested. The default run_listener.py and run_panel.py constructors do not pass a registry, so do not describe registry-backed routing as the default live runtime for this commit.
Web search is disabled by default in config/zero.example.yaml (web.enabled: false). The public runtime documentation only describes configured official external APIs: Google Grounding through the Gemini route is the supported live-search path in this release line.
SearXNG modules remain in the source tree as legacy/internal code. They are disabled by default, are not a hosted Zero service, and are not advertised as a public fallback or supported public feature.
The repository also contains Telegram Search code, but the legacy configuration defaults it to disabled and archived, and the panel documentation excludes it from the public release/UI. It is not advertised here as a public feature.
The current runtime has a Memory V3 service and the normal prompt path is tested to use V3 data rather than legacy V1 markers. The repository still contains older V1/V2 storage and migration artifacts.
The direct migration tool is:
python scripts/migrate_memory_v1_to_v3.py \
--source /path/to/v1.db \
--target /path/to/v3.db \
--run-id migration-001 \
--dry-runApply mode requires a backup path and matching SHA-256 proof; the tool also supports --verify and --rollback. Migration behavior is locally tested with real temporary SQLite databases. No live production migration is claimed.
Office support is optional and disabled by default. The listener starts Office services only when office.enabled is true. Supported formats in the source are DOCX, XLSX, and PPTX. The workflow uses explicit /docx, /xlsx, or /pptx commands, OOXML preflight, quotas, a persistent queue, an isolated worker, output validation, preview rendering, optional visual review, bounded repair, and idempotent delivery.
The external executable path configured by the example is /usr/local/lib/zero-office/officecli. Rendering also requires a supported Chrome/Chromium backend. The repository's real OfficeCLI integration tests passed in the audit environment, but no live Telegram delivery was performed.
Run the panel with python scripts/run_panel.py. It serves http://127.0.0.1:8787 by default, controlled by ZERO_PANEL_HOST and ZERO_PANEL_PORT. Keep it on loopback and put it behind an authenticated HTTPS reverse proxy if remote access is required. The management bot in the same process is owner-only.
The panel is a real local adapter, not a promise that every maintenance action is available. The current documentation explicitly keeps Telegram mode connections, provider CRUD, group CRUD, backup actions, and maintenance actions behind backend contracts rather than faking them in the UI.
python -m zero tui
python -m zero tui --print
python -m zero tui --print --panel doctorAvailable panels are status, doctor, groups, backup, logs, and setup.
See INSTALLATION.md for system requirements, OS boundaries, credentials, Telegram modes, provider configuration, database/migration commands, Docker caveats, health checks, backups, rollback, troubleshooting, and removal.
Quick manual entry point:
git clone https://github.com/mhrsdev/Zero-Agent.git
cd Zero-Agent
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txtThe repository contains a pinned two-stage Dockerfile, an unprivileged zero user, a read-only filesystem, a /data volume, a health check at /api/health, and Compose services zero-panel and zero-listener.
Important: the current Compose setup requires both configuration layers: canonical JSON at /data/config/zero.json and legacy YAML selected through ZERO_CONFIG_PATH. The Compose file does not provision the legacy YAML path itself. Docker build/run was not locally verified in the audit environment, so Compose must not be treated as a turnkey installation until both layers are provisioned and the path boundary is resolved. See INSTALLATION.md.
python -m zero version
python -m zero status
python -m zero doctor
curl -fsS http://127.0.0.1:8787/api/healthzero doctor performs local checks and does not contact Telegram or an AI provider. It reports Python, runtime-home, canonical-config, SQLite FTS5, and dependency observations. A clean-container Docker health check targets the panel endpoint.
The repository configures pytest with tests/ as its test path. The CI workflow runs compilation, pytest, migration and tenancy checks, CLI smoke checks, lint/security/artifact checks, and a Docker build smoke test. Use:
python -m pytest -q -p no:cacheproviderTests with names such as live_e2e, real_integration, or external-account behavior should not be read as proof that this checkout has successfully authenticated to Telegram, called a paid provider, or delivered a live message.
- Keep bot tokens, Telegram API hashes, session files, provider keys, databases, logs, and runtime state outside version control.
- The bot token file must be private and contain a
BOT_TOKEN=...line; the loader rejects group/world-readable files. - Secret overlays are selected with
ZERO_SECRET_FILEand are permission-checked. - Canonical config stores symbolic secret references, not credential values.
- The listener uses configured group allowlists; the management bot requires the configured owner in a private chat.
- Keep the panel on loopback and use an HTTPS reverse proxy for remote access.
- Office workers are intended to run unprivileged and isolated; keep OfficeCLI and the browser backend patched.
- This alpha has separate legacy YAML runtime and canonical JSON setup layers.
- Provider Registry is optional and not the default listener/panel composition.
- Bot, user-session, and hybrid mode contracts exist, but hybrid is not a single unified production switch.
- SearXNG code is legacy/internal and disabled; it is not a public feature or supported public fallback.
- Telegram Search remains archived/disabled in the public runtime path.
- Docker build/run was not locally verified in this audit because no Docker-compatible engine was installed.
- Office live rendering depends on an external pinned OfficeCLI binary and a compatible browser backend.
- No live Telegram or paid-provider E2E verification is claimed.
- The repository currently contains conflicting licensing files; see the License section below.
The source and tests point to the following evidence-backed work, without implying completion:
- make canonical setup and legacy runtime configuration one coherent path;
- wire Provider Registry profiles into the default composition roots;
- finish and document the supported Telegram transport lifecycle;
- keep public search exposure explicit and separately gated;
- complete operational migration/recovery verification with real deployment artifacts;
- resolve the licensing decision and align
LICENSE,PROPRIETARY_LICENSE, andNOTICE.
This repository does not currently contain CONTRIBUTING.md. Until contribution terms and licensing are resolved, do not infer that pull requests, forks, redistribution, or derivative works are authorized. For private owner-approved work, keep changes narrow, add focused tests, avoid secrets and runtime data, and run the relevant pytest and static checks before requesting review.
The repository contains both an Apache License 2.0 text in LICENSE and a conflicting all-rights-reserved notice in PROPRIETARY_LICENSE, while NOTICE also describes Apache licensing. This is unresolved in the current HEAD. This README does not declare the project open source or grant permission to use, copy, modify, deploy, or redistribute it. Obtain a written licensing decision from the copyright holder before publishing or using the project.