A professional Telegram bot for executing code snippets in multiple programming languages using the Piston API.
- Multi-language Support: Execute code in 50+ programming languages
- Interactive Interface: Button-based language selection and command-line interface
- Professional Architecture: Modular, maintainable code structure
- Error Handling: Comprehensive error handling and retry mechanisms
- Rate Limiting: Built-in rate limiting to prevent abuse
- Channel Membership: Optional requirement for users to join a specific channel
- Health Monitoring: Automatic health checks and resource management
- Docker Support: Containerized deployment with health checks
- Graceful Shutdown: Proper cleanup on termination
- Logging: Comprehensive logging with rotation and colored output
iRunCode/
├── src/ # Source code
│ ├── config/ # Configuration management
│ │ └── __init__.py # Config class and constants
│ ├── handlers/ # Telegram message handlers
│ │ ├── commands.py # Command handlers (/start, /help, etc.)
│ │ └── messages.py # Message handlers
│ ├── services/ # Business logic services
│ │ ├── piston.py # Piston API integration
│ │ └── state.py # User state management
│ ├── utils/ # Utility functions
│ │ ├── logger.py # Logging configuration
│ │ ├── helpers.py # Helper functions and decorators
│ │ └── health.py # Health monitoring
│ └── main.py # Application entry point
├── logs/ # Log files (auto-created)
├── .env # Environment variables
├── requirements.txt # Python dependencies
├── Dockerfile # Docker configuration
├── docker-compose.yaml # Docker Compose configuration
├── run.py # Startup script
└── README.md # This file
- Python 3.8+
- Docker (optional, for containerized deployment)
-
Clone the repository
git clone <your-repo-url> cd iRunCode
-
Create and activate virtual environment
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
-
Install dependencies
pip install -r requirements.txt
-
Configure environment variables
cp .env.example .env # Edit .env with your Telegram Bot API key
-
Run the bot
python run.py # or python -m src.main
-
Configure environment
# Make sure .env file exists with your API_KEY echo "API_KEY=your_telegram_bot_token_here" > .env
-
Build and run with Docker Compose
docker-compose up -d --build
-
View logs
docker-compose logs -f iruncode-bot
-
Stop the bot
docker-compose down
The bot supports optional channel membership requirements to encourage users to join your channel before using the bot:
- Enable the feature by setting
REQUIRE_CHANNEL_MEMBERSHIP=true
in your.env
file - Set the channel using
REQUIRED_CHANNEL_ID
with either:- Public channel:
@your_channel_username
- Private channel:
-1234567890123
(channel ID)
- Public channel:
When enabled, users who aren't members of the specified channel will receive a message prompting them to join before they can use the bot's features.
For private channels, you need the channel ID:
- Add your bot as an admin to the channel
- Forward a message from the channel to @userinfobot
- Use the channel ID (negative number) in your configuration
Create a .env
file in the root directory with the following variables:
# Required
API_KEY=your_telegram_bot_token_here
# Optional - with defaults
LOG_LEVEL=INFO
LOG_FILE=logs/bot.log
PISTON_API_URL=https://emkc.org/api/v2/piston/execute
PISTON_TIMEOUT=30
PISTON_RETRY_ATTEMPTS=3
PISTON_RETRY_DELAY=1.0
BOT_TIMEOUT=30
POOLING_TIMEOUT=30
CONNECTION_POOL_SIZE=8
RATE_LIMIT_WINDOW=60
RATE_LIMIT_MAX_REQUESTS=10
HEALTH_CHECK_INTERVAL=300
MAX_MEMORY_USAGE=256
# Channel Membership Requirements (Optional)
REQUIRE_CHANNEL_MEMBERSHIP=false
REQUIRED_CHANNEL_ID=@area51_blog
/start
- Start the bot and show language selection/help
- Show help message with usage instructions/about
- Show information about the bot/langs
- List all supported programming languages/run <language> <code>
- Execute code directly
Button Interface:
- Send
/start
- Click on a language button (e.g., "🐍 Python")
- Send your code
- Receive the output
Command Interface:
/run python
print("Hello, World!")
Supported Languages: Python, C++, C#, JavaScript, Java, Go, Rust, PHP, C, Bash, and 40+ more languages.
- Connection Pooling: Efficient HTTP connection management
- Retry Mechanisms: Automatic retries with exponential backoff
- Error Handling: Comprehensive error catching and user feedback
- Rate Limiting: Prevents API abuse and bot overload
- Health Monitoring: Automatic resource monitoring and cleanup
- Graceful Shutdown: Proper cleanup on termination
- Memory Management: Automatic cleanup of inactive users
- Modular Design: Separated concerns into logical modules
- Configuration Management: Centralized configuration with validation
- Professional Logging: Structured logging with rotation and colors
- Type Hints: Full type annotations for better code quality
- Async/Await: Proper asynchronous programming throughout
- Docker Support: Production-ready containerization
- Channel Integration: Optional channel membership requirements
- Channel Membership: Configurable requirement for users to join a specific channel before using the bot
- Automatic Verification: The bot automatically checks if users are members of the required channel
- Flexible Configuration: Can be enabled/disabled and configured for any public or private channel
- Async HTTP Client: Non-blocking HTTP requests
- Connection Reuse: Persistent HTTP connections
- Memory Optimization: Automatic cleanup of old data
- Efficient State Management: Optimized user state storage
The bot includes comprehensive monitoring:
- Health Checks: Automatic system health monitoring
- Memory Usage: Tracks and limits memory consumption
- User Activity: Monitors and cleans up inactive users
- API Performance: Tracks API response times and errors
- Logging: Detailed logs with different levels
- Commands: Add to
src/handlers/commands.py
- Message Handlers: Add to
src/handlers/messages.py
- Services: Add business logic to
src/services/
- Configuration: Update
src/config/__init__.py
# Run with debug logging
LOG_LEVEL=DEBUG python run.py
# Monitor resource usage
docker stats iruncode
- Bot stops responding: Check logs and restart the container
- High memory usage: Adjust
MAX_MEMORY_USAGE
in environment - API timeouts: Increase
PISTON_TIMEOUT
setting - Rate limiting: Adjust rate limit settings in configuration
Logs are written to:
- Console (with colors)
logs/bot.log
(with rotation)
Use different log levels for different environments:
DEBUG
: DevelopmentINFO
: ProductionWARNING
: Production with minimal logsERROR
: Only errors
- Fork the repository
- Create a feature branch
- Make your changes following the existing code style
- Add tests if applicable
- Submit a pull request
- Piston API by Engineer Man
- Built with ❤️ for the community
This project is open source. See the LICENSE file for details.