mcp server

zero-ai

Toni-cs/zero-aicommunitylistedunreviewed

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "zero-ai": {
      "command": "uvx",
      "args": [
        "zero-ai-cli"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 26, 2026

ZeroAI

English | 简体中文

A Terminal AI Collaboration Platform for Research and Engineering

Multi-expert collaboration · Academic literature search · National-standard document generation · Security audit · Cross-platform SSH operations · Local system operations

Abstract

ZeroAI is a terminal AI collaboration platform built for researchers and developers. It uses a multi-expert collaboration architecture that brings task planning, code generation, deep reasoning, academic writing, literature search, document generation, security auditing, and remote operations into a single terminal environment — cutting down the cost of switching between tools and improving research throughput.

The system is purpose-built for research workflows: it queries the open OpenAlex index with Crossref as an automatic fallback — neither requires an API key — with filtering by publication year and ranking by citation count; it ships a LaTeX formula rendering engine that converts fractions, radicals, matrices, limits, summations, and integrals into Unicode and high-resolution PDF images; it generates Word/PDF academic documents that follow the GB/T 7713.1-2025 national standard; it provides an offline speech recognition engine to keep research data private; and its proxy server architecture delivers zero API key exposure for secure team collaboration.

Roadmap: the ZeroAI Teaching Desktop App (updated 2026-10-12)

On top of the terminal product, ZeroAI is developing a second product line: a self-contained digital-teaching desktop application — voice + AI-computer-operation + a deterministic teaching-rhythm layer, aimed at classroom demonstration and tutoring. This repository stays the single home of the ZeroAI engine; the desktop shell is built from a pinned fork of the MIT-licensed OpenCode desktop app.

Final architecture (decided 2026-10-11/12)

ZeroAI.exe   (fork of @opencode-ai/desktop v2.0.26, MIT — rebranded; engine 2.0.26)
  ├─ intact OpenCode: sessions / model selector / permissions / skills / terminal / file tree
  ├─ model brain: OpenCode's own provider system (auth.json / opencode-go gateway)
  │     — every model in OpenCode stays usable, no extra "server" is bolted on
  ├─ injected layer: ZeroAI branding + preset MCP config (mcp.zeroai, 65 tools)
  ├─ voice layer: MOSS-Transcribe-Diarize 0.9B as the only teaching ASR
  │     (no automatic SenseVoice fallback — debug switch `ZEROAI_ASR_ENGINE`
  │     retained for troubleshooting), edge-tts narration, time-based VAD
  │     (3 s pre-speech window; silence judged in real seconds)
  ├─ computer-operation layer: Windows-MCP v4.1.0 (MIT, 20 tools)
  │     App / Snapshot / Click / Type / Scroll / Move / Shortcut / PowerShell /
  │     FileSystem / Process / Registry ...  (tool allowlist configurable)
  ├─ browser layer: browser-use 0.13.x (MIT core) — B1 stepping primitives
  │     + B2 autonomous runs, isolated in a dedicated engine venv
  ├─ teaching-rhythm layer: step-by-step narration where cadence parameters live
  │     inside the tool contracts (Type-per-keystroke, Wait, WaitFor) — the lesson
  │     plan is written once by the LLM, the pace is executed deterministically
  └─ deliberately NO on-screen avatar — the screen hosts the lesson itself

Verified groundwork `[已确证]`, evidence under `evals/`

Conclusion	Evidence
OpenCode tree is MIT	LICENSE read from the local clone
Desktop shell lives in the monorepo	`packages/desktop`: 126 files / 7,651 lines (TS/TSX)
Engine contract intact	MCP config shape A and B accepted; `/mcp` zeroai connected; `POST /session` 200 (e2e on 1.18.35; 2.0.26 proven by this very desktop harness)
MOSS chose end-to-end	TTS→ASR closed loop: character similarity 1.000
Desktop-operation tooling	Windows-MCP 4.1.0 stdio handshake + `tools/list` = 20 tools on this machine
Teaching VAD judges real seconds	`tests/test_vad_time_based.py` 4/4

Milestones

M2' fork the v2.0.26 desktop app, rebrand, ship a runnable ZeroAI.exe
M3' inject MCP presets + voice/teaching overlays + Windows-MCP / browser-use sidecars
M4' NSIS packaging + on-demand model weights + electron-updater
M5' (optional) a local Ollama brain — OpenCode already accepts OpenAI-compatible endpoints

Open decisions

Whether MOSS weights (~1.7 GB) ship inside the installer or download on first run (default plan: on-demand download)
Teaching rhythm depth — tool-level cadence (M2a) first, engine-level lesson player (M2b) later

Licensing stack

Component	License
OpenCode desktop base (v2.0.26 fork)	MIT, upstream copyright retained
MOSS-Transcribe-Diarize 0.9B	Apache-2.0
Windows-MCP	MIT
browser-use	MIT core (upstream replaced the AGPL `PyMuPDF` transitive dependency with BSD-family `pypdf`)

Research Value

1. Academic Literature Search and Review Assistance

Queries the open OpenAlex scholarly index with Crossref as an automatic fallback — neither requires an API key — and supports:

Literature search by keyword, author, or DOI
Ranking by citation count and filtering by publication year
Automatic generation of a literature review draft, helping researchers grasp a field quickly
Free to use: formatting runs offline and literature search needs no API key. Each source still enforces its own server-side quota — when one is rate-limited the tool automatically falls back to the other, and reports failure honestly if both are unavailable

2. Academic Formula Derivation and Rendering

Built-in LaTeX formula rendering engine, supporting:

Inline formulas $...$ and display formulas $$...$$ in dual mode
Academic symbols including fractions, radicals, super/subscripts, Greek letters, matrices, limits, summations, integrals, and partial derivatives
Display formulas rendered to high-resolution images via matplotlib mathtext, ready to embed in PDF/Word
Unicode output compatible with both terminal display and document typesetting

3. National-Standard Academic Document Generation

Generated in accordance with GB/T 7713.1-2025, Presentation of scientific and technical reports, dissertations and scientific papers:

Four-level heading hierarchy (# through ####)
Automatic reference formatting
Mixed layout of academic formulas, tables, and images
Dual-format output (.docx / .pdf) conforming to academic publishing conventions

4. Multi-Expert Collaborative Research

Seven experts collaborate on a single research question, coordinated by the project manager:

Academic Research Expert: literature review, formula derivation, paper writing
Reasoning Expert: mathematical proof, logical analysis, complexity analysis
Coding Expert: algorithm implementation, experiment code, data processing
Project Manager: task decomposition, result aggregation, multimodal analysis
Well suited to cross-disciplinary research (e.g. computational linguistics, bioinformatics, computational social science)

5. Offline Speech Recognition and Data Privacy

Default engine MOSS-Transcribe-Diarize 0.9B (OpenMOSS, Apache-2.0; 1st place, INTERSPEECH 2026 MLC-SLM challenge); SenseVoice (Alibaba DAMO Academy) is kept as a legacy fallback / debug engine
50+ languages including Chinese and English; MOSS transcription is timestamped and speaker-tagged, which also lays the groundwork for meeting transcription
Speech recognition, document generation, and formatting run locally; agent tasks call a configured model API (GLM / OpenRouter / Ollama), so task text does leave the machine unless a local model is used
Document generation and formatting run locally with no API key; academic search uses public APIs and may be rate-limited

6. Team Collaboration and API Key Isolation

The proxy server architecture achieves zero API key exposure:

Real API keys live only in the server-side .env file
Clients hold only an access token, fully separated from the upstream keys
Per-user token assignment for multi-member research groups
Rate limiting and audit logging to prevent abuse and enable traceability

7. Research Code Security Audit

For research code — especially data-processing and statistical-analysis code — the system provides:

Hardcoded secret scanning (to prevent dataset access credential leaks)
Path traversal detection (to prevent accidental deletion of experiment data)
Known-vulnerability checks for dependency packages
Non-intrusive scanning; no penetration testing is performed

System Architecture

Multi-Expert Collaboration Architecture

Expert	Responsibility	Typical Use
Project Manager	Task analysis, scheduling, multimodal	Cross-disciplinary decomposition, image-text analysis
Coding	Code generation, debugging, refactoring	Algorithm implementation, experiment code
Reasoning	Deep reasoning, mathematics, logic	Mathematical proof, complexity analysis
General Knowledge	General Q&A, translation, encyclopedia	Cross-language literature translation, concept lookup
Chinese Writing	Chinese writing, copywriting, reports	Chinese academic writing, research reports
Multimodal	Image understanding, image-text analysis	Chart analysis, experiment result visualization
Academic Research	Academic research, formula derivation, paper writing	Literature review, paper authoring

Hybrid Routing (Zero Latency + Semantic Precision)

ZeroAI uses two-tier hybrid routing that balances speed and precision:

Tier	Trigger Condition	Latency	Implementation
L1 Keyword fast routing	Short messages (<10 characters) or an unambiguous expert keyword hit	0 ms	Local keyword matching + LRU cache
L2 GLM semantic routing	L1 misses (falls back to `knowledge`)	1-2 s	GLM-4V semantic classification + MD5 cache

Workflow:

User input → keyword matching (clear domains such as coder/academic/chinese/reasoner)
Hit → route directly to the corresponding expert (zero latency; most scenarios take this path)
Miss → call GLM-4V for semantic classification (1-2 seconds), caching the result in an LRU (256 entries)
GLM failure → degrade to the General Knowledge expert (never blocks)

Performance advantage: questions with unambiguous keywords — code, papers, writing — are routed with zero latency; only vague questions (such as "take a look at this for me") go through semantic routing. The LRU cache avoids repeated classification, and MD5 digests are used as keys to prevent long-text prefix collisions.

Circuit breaker: an OpenRouter expert that fails three times in a row is automatically tripped, skipping that expert and degrading to GLM so users are not left stuck on "Thinking…".

Automatic Routing Examples

"Prove …" → Reasoning expert (keyword hit)
"Implement …" → Coding expert (keyword hit)
"Paper …" → Academic Research expert (keyword hit)
"Translate …" → General Knowledge expert (keyword hit)
"Take a look at whether this approach is any good" → GLM semantic routing (no keyword hit)

Hybrid Thinking Mode (Multi-Expert Collaboration)

Multiple experts work on the same problem while the project manager consolidates their conclusions — useful for complex research questions such as "design an experiment to validate the hypothesis and analyze statistical significance". In hybrid mode, inter-expert communication runs over a MessageBus (publish/subscribe) plus a Blackboard (shared state), supporting three collaboration strategies: pipeline, role dependency graph, and consensus voting.

Core Features

SSH Remote Deployment (7 tools)

Parallel connections to multiple servers, distinguished by conn_id, with password/key authentication
Remote command execution, with second-confirmation for dangerous commands (11 categories including rm -rf /, mkfs, dd)
SFTP file transfer — upload/download files with automatic permission handling
One-click automated deployment with ssh_deploy (pre_check → mkdir → upload → install → restart → health_check → post_cmds)
Audit log (up to 200 entries), fully traceable
Host address validation, dangerous-command blacklist, optional internal-IP blocking, and output truncation protection

AI Remote Operations (8 semantic tools, cross-platform)

Turns "AI stringing commands together" into "AI invoking semantic tools", reducing hallucination, unifying error handling, and automatically analyzing results. All 8 tools support automatic adaptation across Linux and Windows Server:

Tool	Function
`ssh_service_manage`	systemd wrapper (status/start/stop/restart/enable)
`ssh_log_view`	journalctl wrapper with automatic error-density statistics
`ssh_process_check`	Top N sorted by CPU/memory
`ssh_disk_analyze`	`df` + `du` Top 10, with automatic critical/warning annotation
`ssh_network_diag`	Ports/connections/ping/statistics
`ssh_docker_manage`	Containers/images/logs/resources
`ssh_firewall_manage`	Automatic detection of ufw/firewalld/iptables
`ssh_health_check`	Comprehensive report + AI health analysis + anomaly annotation

AI Operations Decision Chain

Vague problem handling: "the server is slow" → run a health check first → drill down → localize → give recommendations
Explicit troubleshooting: "nginx is down" → check status → if failed → inspect the error log → isolate the root cause
Proactive AI analysis: the health report automatically identifies anomalies in load, disk, swap, failed services, and error logs

Cross-Platform SSH Operations (Linux + Windows Server)

All 8 AI remote operations tools support automatic cross-platform adaptation; on connecting they detect the remote operating system, so users never specify command syntax:

Tool	Linux Implementation	Windows Implementation
`ssh_service_manage`	`systemctl`	`sc.exe` / `Get-Service`
`ssh_log_view`	`journalctl`	`Get-WinEvent` (event log)
`ssh_process_check`	`ps aux`	`Get-Process`
`ssh_disk_analyze`	`df` + `du`	`Get-CimInstance` + `Get-ChildItem` Top 10
`ssh_network_diag`	`ss` / `netstat`	`Get-NetTCPConnection`
`ssh_docker_manage`	Native Docker CLI	Docker Desktop (`docker.exe`)
`ssh_firewall_manage`	`ufw` / `firewalld` / `iptables`	`netsh advfirewall`
`ssh_health_check`	Comprehensive health check (auto-detects OS)	Comprehensive health check (Windows Server metrics)

Why cross-platform matters:

The same natural-language instruction manages both Linux and Windows servers: "check nginx status" executes correctly on either side
Operators do not need to memorize two sets of command syntax, lowering the barrier to cross-platform operations
Command differences are handled inside the tools, so the AI never assembles commands by hand and hallucinates less

Local Operations Tools (4 semantic tools, cross-platform)

Common local machine operations are wrapped as semantic tools that adapt automatically to Windows/Linux, and are preferred over hand-assembled run_command calls:

Tool	Function	Typical Scenario
`local_port_check`	Port/network check	"what ports are open", "is port 80 taken", "ping 192.168.1.1"
`local_process_check`	Process inspection/management	"is the machine bogged down", "find the chrome process", "kill PID 1234"
`local_disk_check`	Disk space analysis	"how much disk is left", "which directory is largest", "the C: drive is full"
`local_service_check`	Service management	"list running services", "MySQL status", "restart the docker service"

Security design:

Anti-injection whitelist: process names/service names may contain only letters, digits, ., _, and -, rejecting injections such as nginx; rm -rf /
Port checks probe via socket connections rather than external commands
Dangerous operations (kill/stop) require explicit parameters

Cross-Platform Command Compatibility (automatic translation in `run_command`)

The run_command tool embeds a Linux ↔ Windows command translation engine, so users can type a command from any platform and the system adapts it to the current operating system:

User on Windows types 'ls -la'      -> automatically executes 'dir -la'
User on Windows types 'cat file'    -> automatically executes 'type file'
User on Windows types 'rm -rf /tmp' -> automatically executes 'rmdir /s /q /tmp'
User on Windows types 'grep x file' -> automatically executes 'findstr x file'
User on Windows types 'ps aux'      -> automatically executes 'tasklist aux'

Translation characteristics:

50+ command mappings covering file operations, networking, services, processes, and package management
Longest-match first: rm -rf matches before rm, preventing mistranslation
Smart skip: when the original command is already in the target platform's format (e.g. netstat -ano), translation is skipped to avoid duplication
Translation notice: after translating, the system prints a notice such as [cross-platform] translated 'ls' to 'dir'

Voice Conversation

Offline speech recognition: MOSS-Transcribe-Diarize 0.9B by default (SenseVoice keeps serving as an automatic legacy fallback when MOSS weights are absent; ZEROAI_ASR_ENGINE=sensevoice forces the legacy engine). No API key required for either engine
Speech synthesis: Edge TTS with male/female voice switching and adjustable speaking rate
Live subtitles: real-time subtitles in conversation mode
Shortcuts: Ctrl+T for single-shot voice input, Ctrl+D for continuous conversation mode

Security Audit

Vulnerability scanning: SQL injection, XSS, hardcoded secrets, path traversal, and more
Dependency checks: scan dependency packages for known vulnerabilities
Configuration audit: inspect configuration files for security issues
Non-intrusive: only scans the project itself; no penetration testing

ReAct Agent Loop (Reasoning-Action Cycle)

The agent framework introduced in Phase 1 goes beyond conventional single-shot tool calls:

Chain-of-thought visualization: shows the full Thought → Action → Observation → Thought process
Plan-and-Execute planning: complex tasks are decomposed into multi-step plans and executed incrementally
Reflexion self-critique: when a tool call fails, the agent analyzes the cause and adjusts its strategy
Parallel tool calling: independent subtasks can run in parallel for higher efficiency
Tool result summarization: long outputs are compressed automatically to avoid context overflow
TUI commands: /react enters Agent mode, /index builds the project index, /memory shows vector memory

Vector Memory and RAG (Retrieval-Augmented Generation)

The long-term memory system introduced in Phase 2 supports semantic context recall:

GLM embedding-3 integration: generates vectors with Zhipu's GLM embedding-3 model
Hybrid retrieval: vector similarity (0.7 weight) fused with BM25 keywords (0.3 weight)
Conversation history vectorization: historical conversations are chunked, vectorized, and stored automatically
Memory decay: memories not accessed for a long time are automatically down-weighted to avoid noise
File background watching: project files are re-indexed automatically when they change, keeping memory fresh
Zero-dependency fallback: when no embedding API is available, it degrades to pure TF-IDF retrieval

MCP Support (Model Context Protocol)

The bidirectional MCP support introduced in Phase 3 lets ZeroAI act either as an MCP Server exposing its tools to external clients, or as a Client connecting to external MCP servers:

JSON-RPC 2.0 core: a complete implementation of the MCP specification
stdio / SSE dual transport: supports both local subprocesses (stdio) and remote services (SSE)
Automatic tool registration: after connecting to an external MCP Server, its tools are registered into the ZeroAI tool table automatically
65 tools exposed: as an MCP Server, it exposes all 65 built-in tools to clients such as Claude Desktop
Claude Desktop configuration example: a ready-to-use configuration is provided at zeroai/mcp/examples/claude_desktop_config.json
Launching: start the MCP Server with python -m zeroai.mcp

Architecture change note: the Phase-D mixed-language acceleration layer (zeroai-tui/, C/Zig terminal rendering) was removed on 2026-10-10. A same-process benchmark measured a median speed-up of 0.9x (i.e. slower than plain Python), while a rendered frame takes 0.08 ms against LLM calls measured in seconds — under 1% of total latency. The wheel also shipped 13 dead zeroai_tui/*.py files. For the old tree, use git show <rev>:zeroai-tui/build.zig.

Installation

Option 1: pip install (recommended)

pip install zero-ai-cli

Option 2: Install from source

git clone https://github.com/Toni-cs/zero-ai.git
cd zero-ai-cli
pip install -e .

Optional: install voice support

pip install zero-ai-cli[voice]

Voice support includes sherpa-onnx (speech recognition), faster-whisper (fallback recognition), and av (audio processing).

On GPU machines the default engine is MOSS-Transcribe-Diarize 0.9B (weights ~1.7 GB under models/moss-transcribe-diarize/); when those weights are absent ZeroAI automatically degrades to the bundled SenseVoice path (~220 MB downloaded from the HuggingFace mirror on first use).

On first use, the SenseVoice model (~220 MB) is downloaded automatically from the HuggingFace mirror; after that it runs offline.

Usage

After installation, type this in any terminal:

zeroai

Or use the Python module entry point (recommended):

python -m zeroai                    # default Textual UI (recommended)
python -m zeroai --expert coder     # specify an expert directly
python -m zeroai --version          # print the version

Architecture change note: as of v1.1.3 the project was refactored from the single-file tui_agent.py into the modular zeroai package. tui_agent.py was removed entirely on 2026-10-06 — python -m zeroai (or the zeroai console script) is the one entry point. For the old file, use git show <rev>:tui_agent.py. The --ui option was removed on 2026-10-10 together with the zeroai-tui back end; Textual is now the only UI. Existing zeroai --ui textual invocations are still accepted (unknown arguments are ignored).

First-Time Configuration

Option A: Direct mode (personal use)

Get a GLM API key (free): sign up at https://open.bigmodel.cn/ and create a key
After launching ZeroAI, press Ctrl+P to open the settings panel
Enter your GLM API key and save
Alternatively, set the environment variable: ZEROAI_API_KEY_GLM=your_key

Option B: Proxy mode (team collaboration, recommended)

Access AI models through a proxy server, with zero API key exposure on the client:

Deploy the proxy server (see "Proxy Server Deployment" below)
After launching ZeroAI, press Ctrl+P to open the settings panel
In the "Proxy Server" section, configure:
- Proxy address: http://<server-ip>:8000/v1
- Access token: assigned by the administrator
- Proxy mode: enabled
All requests are forwarded through the proxy automatically; the real key stays on the server

Command Reference

Every command also accepts a Chinese alias, and both aliases work at any time. The table below lists the English form; the Chinese aliases are documented in the Chinese README.

Basic Commands

Command	Description
`/help`	Show help
`/clear`	Clear the screen
`/new`	Start a new conversation
`/exit`, `/quit`	Exit the program

Mode Switching

Command	Description
`/expert`	Switch to expert mode (automatic routing)
`/hybrid`	Switch to hybrid thinking (multi-expert collaboration)
`/manual`	Switch to manual mode (specify a model)
`/model`	Show the current model and expert team
`/model glm`	Switch to Zhipu GLM
`/model glm-v`	Switch to Zhipu GLM-4V (multimodal)
`/model openrouter`	Switch to OpenRouter
`/model ollama`	Switch to Ollama (local model)

Agent, Index and Memory

Command	Description
`/react`	Switch to ReAct Agent mode
`/init`	Analyze the project structure and generate `AGENTS.md`
`/index`	Build the project vector index (enables RAG retrieval)
`/memory`	Show vector memory statistics
`/mcp`	MCP protocol management (list/install/connect/tools)

Voice Interaction

Command	Description
`/voice`	Toggle automatic reading of AI replies
`/dialog`	Enter voice conversation mode
`/stop`	Stop voice conversation mode
`/voice_female`	Switch to a female voice (Xiaoxiao)
`/voice_male`	Switch to a male voice (Yunxi)
`/voice_rate +10%`	Set the speaking rate
`Ctrl+T`	Single-shot voice input
`Ctrl+D`	Voice conversation mode

Other Features

Command	Description
`/image`, `/img`	Paste an image from the clipboard
`/copy`	Copy the most recent reply
`/copy N`	Copy the Nth code block from the most recent reply
`/audit`	Security audit
`/ssh`	Show the SSH remote deployment + AI operations toolset (15 tools)
`Ctrl+G`	Paste-image shortcut
`Ctrl+N`	New conversation
`Ctrl+P`	Settings panel
`Ctrl+W`	Companion mode
`Ctrl+Y`	Copy

Language note: the CLI ships both English and Chinese command aliases, and both work at any time. The AI's replies follow the language configuration of the selected expert (Chinese by default). The Chinese command aliases are listed in the Chinese README.

Proxy Server Deployment (Team Collaboration)

The proxy server achieves zero API key exposure and is designed for research groups, laboratories, and enterprise teams.

Architecture

Client (zeroai)  --token auth-->  Proxy server  --real key-->  Upstream AI (GLM/OpenRouter)
                                       |
                                       +- Rate limiting (30 req/min/IP)
                                       +- Model allowlist
                                       +- Streaming SSE pass-through
                                       +- Audit logging

Deployment Steps

Upload the zeroai-proxy/ directory to the server
Install dependencies: pip install -r requirements.txt

Configure .env (copy from .env.example, which lists every available option):

GLM_API_KEY=your_zhipu_key
OR_API_KEY=your_openrouter_key
CLIENT_TOKENS=access_tokens_generated_for_each_member
ALLOWED_MODELS=glm-4.7-flash,glm-4-flash,glm-4v-flash

Start the service (choose Linux systemd / Windows NSSM / Docker)
Open port 8000 in the firewall (internal network only)
Configure the proxy address and token on the client and it is ready to use

Security Features

Feature	Description
API key isolation	The real key lives only in the server `.env`; clients can never obtain it
Token authentication	Clients use independent tokens, fully separated from upstream keys
Rate limiting	Sliding window of 30 requests/minute per IP (configurable)
Model allowlist	Prevents clients from invoking expensive models
Streaming pass-through	Full SSE support; streaming output is unaffected
OpenAI compatibility	No SDK changes on the client; only the base URL changes
Log auditing	Records IP/token/model/status for traceability

IP Security Design (v1.2.0 security hardening)

In response to the security threats a proxy server faces in team/internal deployments, v1.2.0 introduces systematic IP and token hardening:

1. Token Ownership and Lifecycle Management

Capability	Description
Token ownership	Each token is bound to a user name, team, and note for audit traceability
Usage statistics	Automatically records call count and last-used time
Expiry	Supports permanent tokens or a specified expiry (ISO 8601)
Instant revocation	Editing `tokens.json` takes effect via hot reload, with no service restart
State restoration	A revoked token can be reinstated
Statistics reset	A token's usage counters can be reset
Management endpoints	`/admin/tokens` to view, `/admin/revoke` to revoke (requires `ADMIN_TOKEN`)

Token file format (tokens.json):

{
  "abc123def456...": {
    "user": "alice",
    "team": "dev-team",
    "revoked": false,
    "expires": null,
    "usage_count": 0,
    "last_used": null,
    "created_at": "2026-07-25T10:00:00"
  }
}

2. Brute-Force Protection

Parameter	Default	Description
`MAX_FAILURES`	5	Consecutive failures from the same IP before a ban is triggered
`BAN_MINUTES`	30	Ban duration (minutes)
`BAN_WINDOW_MINUTES`	10	Failure-counting window (minutes)

An IP that fails 5 times within a 10-minute window is banned automatically for 30 minutes
A successful verification clears that IP's failure record
The ban list can be viewed at /admin/banned (requires ADMIN_TOKEN)

3. HTTPS Encrypted Transport (self-signed certificate)

Generate a self-signed certificate: python generate_cert.py (based on the cryptography library)
Once enabled, tokens are transported encrypted, preventing man-in-the-middle sniffing
Clients set verify_ssl=false to accept the self-signed certificate (internal deployment scenario)
Certificate files (cert.pem / cert.key) are excluded via .gitignore and never enter version control

4. API Documentation Endpoints Disabled

Endpoint	Status	Description
`/docs`	Disabled	Swagger UI is not exposed
`/redoc`	Disabled	ReDoc is not exposed
`/openapi.json`	Disabled	The OpenAPI schema does not leak the interface structure

This prevents attackers from probing system interfaces and parameters through the API documentation.

5. IP-Masked Audit Logging

All IP addresses in logs are masked automatically, keeping only the first two octets:

Original IP: 192.168.10.66  ->  Log: 192.168.xxx.xxx

Protects user privacy while preserving internal auditability
Ban/unban log entries are masked as well

6. Management Endpoint Authentication

/admin/* endpoints require ADMIN_TOKEN authentication (independent of client tokens):

/admin/tokens: list all tokens (masked)
/admin/revoke: revoke a specified token
/admin/reinstate: reinstate a revoked token
/admin/banned: view the currently banned IP list
/admin/unban: unban a specified IP

7. .gitignore Security Exclusions

# Security-related (certificates and token files — never commit)
*.pem
*.key
*.crt
tokens.json
cert.pem
cert.key
*.bak.*

This ensures sensitive files are never committed to version control by accident.

For detailed deployment documentation, see zeroai-proxy/README.md.

System Requirements

Python >= 3.10
Operating system: Windows / macOS / Linux
Network: access to the Zhipu GLM API (open.bigmodel.cn) or a proxy server
Voice features: a microphone (voice conversation mode only)
Multimodal: supports png/jpg/jpeg/gif/bmp/webp images

Configuration

Configuration File Location

Windows: %USERPROFILE%\.zeroai\config.json
macOS/Linux: ~/.zeroai/config.json

Environment Variables

Environment Variable	Description
`ZEROAI_API_KEY_GLM`	Zhipu GLM API key (direct mode)
`ZEROAI_API_KEY_OPENROUTER`	OpenRouter API key (direct mode)
`ZEROAI_HOME`	ZeroAI resource directory (where `libs`/`models` live)

Resource Directory Lookup Order

The directory containing the script (development mode)
The directory specified by the ZEROAI_HOME environment variable
The user home directory ~/.zeroai/ (pip install mode)

Tech Stack

Component	Technology
UI framework	Textual TUI
AI interface	OpenAI SDK (compatible with the GLM API)
SSH remote	asyncssh (pure-Python asynchronous SSH)
Speech recognition	MOSS-Transcribe-Diarize 0.9B (default) / SenseVoice (legacy, offline)
Speech synthesis	Edge TTS
Document generation	python-docx + reportlab + matplotlib
Academic formulas	LaTeX → Unicode + matplotlib mathtext
Literature search	OpenAlex API (Crossref fallback, no key)
Proxy service	FastAPI + httpx

Feature Demos

The transcripts below are illustrative and written in English for readability. The built-in interface labels and the default expert replies are in Chinese (several expert system prompts explicitly instruct "answer in Chinese").

Multi-Expert Collaboration

User: Write a Python function that computes the Fibonacci sequence, and analyze its time complexity

-> Project Manager · GLM-4.7 analyzes the task
-> Coding · GLM-4.7 generates the code
-> Reasoning · GLM-4.7 analyzes the complexity
-> Project Manager · GLM-4.7 aggregates the results

Academic Literature Search

User: Search for papers on Transformer acceleration from the last three years, ranked by citations

-> Academic Research expert calls the OpenAlex API (Crossref fallback)
-> Returns 10 highly cited papers (title/author/year/citations/abstract)
-> Automatically generates a literature review draft

Academic Document Generation

User: Generate an academic report on machine learning in Word format, including formulas

-> Academic Research · GLM-4.7 generates the content
-> LaTeX formula rendering: $$E = mc^2$$ -> high-resolution image embedded
-> Automatically typeset per the GB/T 7713.1-2025 format
-> Saved as a .docx file

SSH Remote Deployment

User: Connect to 192.168.10.20 as root with password xxx, and deploy D:/projects/myapp to /opt/myapp

-> ssh_connect establishes the connection (conn_id=default)
-> ssh_deploy one-click deployment:
  1. pre_check    -> check disk space / Python version
  2. mkdir        -> create the /opt/myapp directory
  3. upload       -> SFTP the project files
  4. install      -> pip install -r requirements.txt
  5. restart      -> systemctl restart myapp
  6. health_check -> curl localhost:8080/health
  7. post_cmds    -> clean up temporary files
-> Generates a deployment report

AI Remote Operations

User: The server is slow, take a look at what is going on

-> ssh_health_check one-click health check
  -> system info, CPU, memory, disk, network, load, failed services, error logs
  -> AI analysis: 3 issues found
    1. 1-minute load 5.2 is high
    2. Disk usage 92% (critical)
    3. 15 error log entries in the last hour
  Recommends drilling down

User: How is mysql doing
-> ssh_service_manage(action=status, service=mysql)
-> Automatic status interpretation: running / not running / exited abnormally

User: Check the nginx error log
-> ssh_log_view(service=nginx, keyword=error)
-> Returns the log + automatic statistics: high error density, recommends drilling down

User: Open port 8080
-> ssh_firewall_manage(action=open, port=8080)
-> Automatically detects the firewall type (ufw/firewalld/iptables) and executes

Development

Development Mode Installation

git clone https://github.com/Toni-cs/zero-ai.git
cd zero-ai-cli
pip install -e .           # main package (development mode)
pip install -e ".[dev]"    # development dependencies (build, pyinstaller)
pip install -e ".[voice]"  # optional: voice dependencies

In development mode, changes to the zeroai/ package take effect immediately with no reinstall.

Building

pip install build
python -m build

The generated packages appear in dist/ (.whl and .tar.gz).

Running Tests

# Full test suite (unit + regression + integration)
python -m pytest -q

Project Structure

zero-ai-cli/
├── zeroai/                   # Modular package (recommended entry point, v1.1.3+)
│   ├── core/                 # Core layer (8 submodules)
│   │   ├── paths.py          # Path management
│   │   ├── runtime.py        # Runtime cache and interrupt control
│   │   ├── secrets.py        # Secret and configuration persistence
│   │   ├── constants.py      # Constants and expert team
│   │   ├── expert_route.py   # Expert routing (with LRUCache)
│   │   ├── context_compress.py # Context compression
│   │   ├── model_manager.py  # Model management
│   │   └── response_utils.py # Response handling utilities
│   ├── tools/                # Tool layer (17 submodules, 65 tools)
│   │   ├── file_manager.py   # File operations
│   │   ├── command_exec.py   # Command execution
│   │   ├── voice.py          # Voice interaction (listen_asr / recognize_audio / speak_tts)
│   │   ├── asr_moss.py       # MOSS-Transcribe-Diarize engine (default ASR)
│   │   ├── network.py        # Network operations
│   │   ├── system_check.py   # System checks
│   │   ├── security.py       # Security audit
│   │   ├── doc_gen.py        # Document generation
│   │   ├── academic.py       # Academic research
│   │   ├── window_mgr.py     # Window management
│   │   ├── ssh_ops.py        # SSH remote operations
│   │   └── registry.py       # Tool registry (TOOLS + TOOL_MAP, 65 tools)
│   ├── tui/                  # TUI layer (app.py + 8 app_*.py mixins + support modules)
│   │   ├── colors.py         # Color constants
│   │   ├── markdown.py       # Markdown/LaTeX rendering
│   │   ├── identity.py       # Identity-leak filtering
│   │   ├── widgets.py        # Custom widgets
│   │   ├── screens.py        # Modal dialogs
│   │   ├── app.py            # ZeroAI main application class (lifecycle + skeleton)
│   │   ├── app_*.py          # 8 mixins split out of the former 3,664-line class
│   │   └── icons.py          # Icon loading
│   ├── main.py               # Unified entry point
│   └── __main__.py           # Module entry point (supports python -m zeroai)
├── zeroai-proxy/             # Proxy server (API key protection)
│   ├── main.py               # FastAPI proxy entry point
│   ├── requirements.txt      # Dependency list
│   ├── .env.example          # Configuration template
│   ├── Dockerfile            # Docker deployment
│   ├── docker-compose.yml
│   ├── start.sh              # systemd deployment script
│   └── README.md             # Deployment documentation
├── assets/icons/             # Icon assets
├── pyproject.toml            # Package configuration
├── README.md                 # This documentation
├── CHANGELOG.md              # Changelog
├── CONTRIBUTING.md           # Contribution guide
├── LICENSE                   # Apache-2.0 license
├── AUTHORS                   # Author list
├── install.bat               # Windows one-click installer
├── .local_vendor/             # Vendored third-party source (MOSS inference subtree; the local opencode v2.0.26 fork clone is gitignored)
└── libs/ models/             # Voice dependencies and model weights (development mode, not versioned)

See CONTRIBUTING.md for details.

FAQ

Q: It says "please configure the GLM API key" on startup?

A: Press Ctrl+P to open the settings panel and enter your Zhipu GLM API key. Get one free at https://open.bigmodel.cn/

Q: Voice features are not working?

Make sure the voice dependencies are installed: pip install zero-ai-cli[voice]
On first use the model is downloaded automatically (~220 MB)
Make sure microphone permission is granted

Q: I get a RateLimitError (rate limiting)?

A: The GLM free tier is limited, and the system degrades to other models automatically. If rate limiting happens frequently, you can:

Upgrade your quota on the Zhipu platform
Configure OpenRouter as a fallback
Use your own GLM API key
Deploy a proxy server to manage quota centrally

Q: Are macOS / Linux supported?

A: The core functionality is. Voice features may need additional audio driver configuration on macOS/Linux.

Q: How do I use SSH remote operations?

Simply tell the AI in natural language: "connect to 192.168.10.20 as root with password xxx"
The AI calls ssh_connect to establish the connection
From there you can say things like "check nginx status", "the server is slow, run a health check", "check the mysql error log", "open port 8080", "restart the web container"
The AI automatically calls the corresponding semantic operations tool (ssh_service_manage / ssh_health_check / ssh_log_view / ssh_firewall_manage / ssh_docker_manage, etc.)
Type /ssh to see the full list of 15 SSH/operations tools

Q: Are SSH operations safe?

A: Multiple safeguards are in place:

Dangerous command blacklist: 11 categories including rm -rf /, mkfs, dd, and shutdown require confirm_dangerous=true as a second confirmation
Injection protection: service name/container name whitelist validation rejects command injections such as nginx; rm -rf /
Audit log: all SSH operations are recorded automatically (up to 200 entries), queryable via ssh_list
Host validation: IP/domain format validation with optional internal-IP blocking
Output truncation: command output longer than 8000 characters is truncated automatically to prevent screen flooding

Q: How do I use one-click deployment (`ssh_deploy`)?

A: Just tell the AI what you need deployed and it constructs the deploy_config automatically:

Deploy D:/projects/myapp to /opt/myapp on 192.168.10.20,
install dependencies with pip install -r requirements.txt,
restart with systemctl restart myapp,
health check with curl localhost:8080/health

The AI executes the 7 steps automatically and produces a deployment report.

Q: How does the proxy server protect API keys?

A: Under the proxy server architecture:

The real API key lives only in the server-side .env file (never committed to Git, never present on the client)
The client holds only an access token, fully separated from the upstream key
A packet capture on the client reveals only the token, never the real key
Per-user token assignment supports team collaboration
Tokens can be revoked at any time without affecting the real key

License

Apache License 2.0 — free for personal and commercial use, modification, and redistribution, provided the copyright notice and license text are retained. See LICENSE.

Author

ZeroAI Team. See AUTHORS.

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

Acknowledgements

Zhipu AI - GLM family models
Textual - TUI framework
asyncssh - asynchronous SSH client
sherpa-onnx - speech recognition
OpenAlex - open scholarly index (primary literature source)
Crossref - DOI registry and literature metadata (fallback)
FastAPI - proxy service framework
OpenCode - MIT-licensed desktop base forked for the ZeroAI teaching app
OpenMOSS MOSS-Transcribe-Diarize - default speech recognition engine (Apache-2.0)
Windows-MCP - desktop-operation MCP tooling (MIT)
browser-use - browser automation core (MIT)

ZeroAI — Research collaboration, made efficient