A local multi-channel AI agent with Telegram integration, Azure OpenAI backend, and powerful local tool execution.
- Multi-channel support: Telegram (with abstract interface for Slack/Discord/HTTP)
- Azure OpenAI: GPT-4o or other Azure OpenAI deployments
- Tool execution:
exec- Execute shell commands (git, npm, python, curl, etc.)read- Read files and directorieswrite- Write/create fileshttp- Make HTTP requests
- Security controls: Directory whitelists, command blacklists, domain restrictions
- Conversation memory: Per-user conversation history
- Clone and install:
npm install- Copy and configure environment:
cp .env.example .env
# Edit .env with your credentials- Build and run:
npm run build
npm startOr for development:
npm run dev| Variable | Description |
|---|---|
AZURE_OPENAI_API_KEY |
Your Azure OpenAI API key |
AZURE_OPENAI_ENDPOINT |
Azure OpenAI endpoint URL |
TELEGRAM_BOT_TOKEN |
Telegram bot token from @BotFather |
| Variable | Description | Default |
|---|---|---|
AZURE_OPENAI_DEPLOYMENT |
Model deployment name | gpt-4o |
AZURE_OPENAI_API_VERSION |
API version | 2024-02-15-preview |
TELEGRAM_ALLOWED_USERS |
Comma-separated user IDs | (allow all) |
ALLOWED_DIRECTORIES |
Allowed paths for file ops | $HOME,/tmp,cwd |
BLOCKED_COMMANDS |
Blocked command patterns | (dangerous only) |
ALLOWED_HTTP_DOMAINS |
Allowed domains for HTTP | (all) |
MAX_FILE_SIZE |
Max file size in bytes | 10485760 |
- Send any message to interact with the agent
/clear- Clear conversation history
You: List files in current directory
Agent: [Uses exec tool: ls -la]
Here are the files...
You: Read the package.json file
Agent: [Uses read tool]
The package.json contains...
You: Create a hello.txt file with "Hello World"
Agent: [Uses write tool]
Created hello.txt...
You: Make a GET request to httpbin.org/ip
Agent: [Uses http tool]
Your IP is...
npm run build
npm run pm2:start
# Other PM2 commands
npm run pm2:stop
npm run pm2:restart
npm run pm2:logsCreate /etc/systemd/system/x-super-agent.service:
[Unit]
Description=X-Super-Agent
After=network.target
[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/x-super-agent
ExecStart=/usr/bin/node dist/index.js
Restart=on-failure
EnvironmentFile=/path/to/x-super-agent/.env
[Install]
WantedBy=multi-user.target- By default, security restrictions are relaxed to allow most operations
- Configure
TELEGRAM_ALLOWED_USERSto restrict bot access - Configure
ALLOWED_DIRECTORIESto limit file operations - Configure
BLOCKED_COMMANDSto prevent dangerous commands - The agent can execute most shell commands - use with care
src/
├── core/
│ ├── types.ts # Type definitions
│ ├── llm.ts # Azure OpenAI client
│ └── agent.ts # Agent loop implementation
├── tools/
│ ├── index.ts # Tool registry
│ ├── exec.ts # Shell command execution
│ ├── read.ts # File reading
│ ├── write.ts # File writing
│ ├── http.ts # HTTP requests
│ └── security.ts # Security configuration
├── channels/
│ ├── base.ts # Abstract channel interface
│ ├── telegram.ts # Telegram implementation
│ └── index.ts # Channel exports
└── index.ts # Entry point
Implement the BaseChannel abstract class:
import { BaseChannel } from './base';
export class MyChannel extends BaseChannel {
name = 'my-channel';
async start(): Promise<void> {
// Initialize and start listening
}
async stop(): Promise<void> {
// Cleanup
}
}MIT