Opsyra

An autonomous AI coding agent orchestrator and workspace manager for Telegram, built on top of mtcute (Telegram MTProto client).

Opsyra integrates CLI coding agents (Claude Code, OpenAI Codex, Antigravity) directly into Telegram topics and direct messages, providing real-time token streaming drafts, tool call tracking, reasoning blocks, and sandboxed workspace execution.

Note: This project is in active development. Some features may be incomplete or contain bugs, which will be addressed in upcoming releases. The documentation and inline codebase comments were generated by Gemini.

---

Features

• MTProto Streaming Drafts: Real-time token streaming using Telegram's native typing draft actions with dynamic thinking indicators and expandable reasoning blocks.
• Agent Flow Management: Run persistent, multi-turn AI agent sessions inside dedicated Telegram forum topics or DMs.
• Multi-Environment Workspaces:
  • Host Workspace: Run agent commands directly on the host machine.
  • Branch Isolation: Sandboxed Linux OS users for individual branches or projects.
  • Remote SSH: Connect and orchestrate agents on remote Linux servers via SSH.
• Live Tool Tracking: Real-time inspection cards for running bash commands, file modifications, and web fetches.
• Access Control: Role-based permissions (Admin, Superuser, Privileged, User) with message gating.
• Storage: External MongoDB support with automatic fallback to an embedded MongoDB instance.

---

Quick Start

Prerequisites

• Node.js: 20.x or 22.x+
• Telegram API Credentials: API_ID and API_HASH from my.telegram.org/apps
• Telegram Bot Token: Created via @BotFather
• MongoDB: Optional (embedded persistent storage will be used if external MongoDB is unavailable)

Setup

1. Clone the repository:

   git clone https://github.com/playeon/opsyra.git
   cd opsyra

2. Install dependencies:

   npm install

3. Create your environment configuration:

   cp .env.example .env

   Open .env and fill in your API_ID, API_HASH, BOT_TOKEN, and ADMINS (your Telegram User ID).

4. Build and start:

   # Development (with watch mode)
   npm run dev
   
   # Production build & run
   npm run build
   npm start

---

Configuration Reference

Variable	Description	Default
API_ID	Telegram API App ID from my.telegram.org	Required
API_HASH	Telegram API Hash from my.telegram.org	Required
BOT_TOKEN	Telegram Bot Token from @BotFather	Required
ADMINS	Comma-separated list of initial admin Telegram User IDs	Required
PRIVATE_ONLY	Restricts bot access to admins and authorized users	true
MONGO_URI	External MongoDB connection string	mongodb://127.0.0.1:27017
MONGO_DB	Database name	opsyra
SESSION_PATH	Storage path for MTProto session file	bot-data/opsyra

---

Project Structure

src/
├── index.ts                # Application entrypoint & command registration
├── config.ts               # Environment variable validation
├── client.ts               # mtcute TelegramClient instance
├── gate.ts                 # Access control middleware
├── commands/
│   ├── emoji.ts            # Telegram custom emoji inspector
│   └── dm/                 # DM commands and setup wizards
│       ├── flow.ts         # Agent flow execution & streaming engine
│       ├── workspaces.ts   # Workspace and branch management
│       ├── role-management.ts # User permissions manager
│       ├── antigravity-setup.ts
│       ├── claude-setup.ts
│       └── codex-setup.ts
├── db/                     # MongoDB models and connection handlers
│   ├── mongo.ts            # MongoDB connection & embedded fallback
│   ├── users.ts            # User documents
│   ├── workspaces.ts       # Workspace metadata
│   ├── branches.ts         # Branch configs
│   └── flows.ts            # Persistent flow sessions
└── utils/                  # Helper utilities
    ├── streaming-indicator.ts # Native Telegram draft animation engine
    ├── markdown-parser.ts  # Markdown to Telegram HTML converter
    ├── local-exec.ts       # Local process execution
    ├── ssh.ts              # Remote SSH executor
    └── rich-message.ts     # UI rendering components

---

Production Deployment (systemd)

To run Opsyra as a continuous background service on Linux:

1. Create a systemd service file at /etc/systemd/system/opsyra.service:

   [Unit]
   Description=Opsyra Telegram Bot
   After=network.target
   
   [Service]
   Type=simple
   User=root
   WorkingDirectory=/opt/opsyra
   ExecStart=/usr/bin/node /opt/opsyra/dist/index.js
   Restart=always
   RestartSec=5
   Environment=NODE_ENV=production
   
   [Install]
   WantedBy=multi-user.target

2. Enable and start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable --now opsyra

3. Check logs:

   journalctl -u opsyra -f

---

Bot Commands

• /start — Open control panel and status dashboard
• /newflow — Start a new AI agent flow session
• /flows — View and manage running flow sessions
• /stop — Stop current active agent response generation
• /destroy — Terminate and clean up flow sessions
• /workspaces — Manage local and remote agent workspaces
• /update — Synchronize agent tools and workspace configurations
• /e — Inspect Telegram custom emoji IDs

---

License

This project is licensed under the Attribution & Personal Use License. You are free to use, run, study, and modify it for personal and internal purposes. Any public redistribution, fork, or sharing must retain the original copyright and prominent attribution back to Opsyra. Redistribution without credit is strictly prohibited. See LICENSE for full terms.