Agentra is a powerful personal AI assistant that runs on your own devices. It provides a local-first AI experience with multi-channel support, task automation, and comprehensive CLI tools.
Requirements: Node.js ≥18
# Install globally
npm install -g agentra@latest
# Run onboarding wizard (sets up everything)
agentra onboard --install-daemon
# Start the gateway
agentra gateway --port 18789 --verbose
# Talk to your AI agent
agentra agent --message "Hello, what can you help me with?"
# Open WebChat interface
# Visit: http://localhost:18789
# Using npm
npm install -g agentra@latest
# Using pnpm
pnpm add -g agentra@latest
# Using yarn
yarn global add agentra@latest
agentra --version
# Should output: 1.0.5 (or latest version)
agentra --help
# Shows all available commands
# Clone repository
git clone https://github.com/saisreesatyassss/agentra.git
cd agentra
# Install dependencies
npm install
# Build project
npm run build
# Run from source
npm run dev -- --help
agentra onboardInteractive setup wizard that configures your entire Agentra environment.
# Basic onboarding
agentra onboard
# Onboarding with daemon installation
agentra onboard --install-daemon
What it does:
Example interaction:
Welcome to Agentra! Let's get you set up.
? What's your name? John Smith
? What's your email? john@example.com
? Choose AI provider: Anthropic Claude
? Enter your Anthropic API key: [hidden input]
✅ Configuration saved successfully!
agentra gatewayStarts the main gateway server that handles all communication channels.
# Start on default port (18789)
agentra gateway
# Custom port and host
agentra gateway --port 3000 --host 0.0.0.0
# Verbose logging
agentra gateway --port 18789 --verbose
# All options combined
agentra gateway --port 8080 --host localhost --verbose
Options:
-p, --port <port> - Port number (default: 18789)-h, --host <host> - Host address (default: localhost)-v, --verbose - Enable verbose loggingFeatures provided:
http://localhost:18789/health, /statusagentra agentInteract directly with your AI assistant via command line.
# Basic conversation
agentra agent --message "What's the weather like?"
# Different thinking levels
agentra agent -m "Explain quantum computing" --thinking high
agentra agent -m "Say hello" --thinking low
# Send response to specific channel
agentra agent -m "Daily report" --channel telegram
# All options
agentra agent --message "Complex analysis task" --thinking high --channel webchat
Options:
-m, --message <message> - Message to send (required)-t, --thinking <level> - AI thinking depth: low|medium|high (default: medium)--channel <channel> - Deliver response to specific channelThinking Levels:
low - Quick, simple responsesmedium - Balanced depth and speedhigh - Deep analysis, detailed responsesExample:
agentra agent -m "Write a Python function to calculate fibonacci numbers" --thinking high
🤖 Agent Response:
Here's an efficient Python function to calculate Fibonacci numbers:
def fibonacci(n):
if n <= 1:
return n
a, b = 0, 1
for _ in range(2, n + 1):
a, b = b, a + b
return b
# Usage examples:
print(fibonacci(10)) # Output: 55
print(fibonacci(20)) # Output: 6765
agentra daemonRun the AI agent as a background service that continuously monitors and responds.
# Start daemon with default settings
agentra daemon
# Custom check interval (in minutes)
agentra daemon --interval 10
# Enable automatic task execution
agentra daemon --auto-tasks
# High thinking level with auto-tasks
agentra daemon --thinking high --auto-tasks --interval 5
Options:
-i, --interval <minutes> - Check interval in minutes (default: 5)-t, --thinking <level> - AI thinking level (default: medium)--auto-tasks - Enable automatic task executionWhat it does:
agentra channelManage communication channels (Telegram, WebChat, etc.).
agentra channel list
Output:
📱 Configured Channels:
Agentra Telegram Bot (telegram): ✅ enabled
WebChat Interface (webchat): ✅ enabled
Development Bot (telegram): ❌ disabled
agentra channel add telegram
Interactive setup:
📝 Setting up Telegram bot...
? Enter your Telegram bot token: 1234567890:ABCdefGHIjklMNOPqrsTUVwxyz
? Enter a name for this bot: My Agentra Bot
? Enable this channel immediately? Yes
✅ Telegram channel added successfully!
🚀 Starting Telegram bot...
To get Telegram bot token:
/newbot# Future channel types (in development)
agentra channel add discord # Coming soon
agentra channel add whatsapp # Coming soon
agentra channel add slack # Coming soon
# Remove by type (will prompt if multiple exist)
agentra channel remove telegram
# Interactive selection if multiple channels exist
# Start specific channel type
agentra channel start telegram
# Stop specific channel type
agentra channel stop telegram
# Start all enabled channels
agentra channel start
# Stop all running channels
agentra channel stop
agentra runStart and run channels with optional AI agent daemon.
# Run all enabled channels
agentra run
# Run specific channel type only
agentra run --channel telegram
# Run channels + AI daemon
agentra run --with-agent
# Run with custom agent interval
agentra run --with-agent --interval 10
# Run specific channel with agent
agentra run --channel telegram --with-agent --interval 5
Options:
-c, --channel <type> - Run specific channel type only--with-agent - Also run the AI agent daemon--interval <minutes> - Agent check interval (default: 5)agentra modelsConfigure and manage AI model providers.
agentra models --list
# or simply
agentra models
Output:
🤖 Configured AI Models:
anthropic: apikey
openai: apikey
# Add Anthropic Claude (recommended)
agentra models --add anthropic
# Add OpenAI GPT
agentra models --add openai
# Add Google Gemini
agentra models --add gemini
Note: For interactive setup with API key entry, use:
agentra onboard
agentra models --remove anthropic
agentra models --remove openai
Supported Providers:
agentra taskManage scheduled tasks and automation.
agentra task list
Output:
📋 Scheduled Tasks:
daily-backup (enabled)
Type: backup
Schedule: 0 2 * * * (Daily at 2 AM)
Next run: 2026-02-24 02:00:00
weather-report (disabled)
Type: message
Schedule: 0 8 * * 1-5 (Weekdays at 8 AM)
Target: telegram
# Interactive task creation
agentra task add
Example interaction:
? Task name: morning-briefing
? Task type:
❯ message - Send automated message
backup - Create data backup
agent - Run agent conversation
custom - Custom command
? Schedule (cron format): 0 8 * * 1-5
? Target channel: telegram
? Message content: Good morning! Here's your daily briefing.
✅ Task 'morning-briefing' created successfully!
# Enable/disable tasks
agentra task enable morning-briefing
agentra task disable daily-backup
# Remove tasks
agentra task remove weather-report
# Show task details
agentra task status morning-briefing
agentra schedulerRun the task scheduler as a standalone service.
# Start scheduler
agentra scheduler
# Verbose logging
agentra scheduler --verbose
What it monitors:
agentra messageSend messages through configured channels.
# Send to Telegram (phone number)
agentra message --to +1234567890 --message "Hello from Agentra!"
# Send to specific channel
agentra message --to @username --message "Meeting reminder" --channel telegram
# Send to multiple recipients
agentra message --to "user1,user2" --message "Group announcement"
Options:
--to <recipient> - Recipient identifier (required)--message <text> - Message content (required)--channel <channel> - Specific channel typeRecipient formats:
+1234567890 or username @usernameagentra doctorComprehensive health check for your Agentra installation.
agentra doctor
Sample output:
🏥 Agentra Health Check
1. User Profile
✅ Profile exists
Name: John Smith
Email: john@example.com
Workspace: /home/john/.agentra
2. AI Models
✅ 2 model(s) configured
- anthropic (apikey) ✅ Valid
- openai (apikey) ✅ Valid
3. Channels
✅ 2 channel(s) configured
- telegram ✅ Connected
- webchat ✅ Available
4. Database
✅ Database healthy
Size: 256 KB
Users: 1, Sessions: 15, Messages: 247
5. Security
✅ Workspace secure
✅ API keys encrypted
✅ Pairing enabled
6. Task Scheduler
✅ 3 task(s) configured
✅ Scheduler healthy
📋 Summary
✅ All systems healthy!
🚀 Agentra is ready to use
What it checks:
agentra databaseAdvanced database operations and maintenance.
agentra database --status
Output:
📊 Database Status:
Available: ✅ Yes
Health: ✅ Healthy
Size: 245 KB
Path: /home/user/.agentra/agentra.db
Table counts:
users: 1
sessions: 23
messages: 156
channels: 2
tasks: 5
agentra database --stats
Detailed breakdown:
📈 Database Statistics:
Health: ✅ Healthy
Users: 1
Sessions: 23
Messages: 156
Channels: 2
Models: 2
Database size: 245 KB
Recent activity:
Last message: 2 minutes ago
Active sessions: 3
Completed tasks: 12
# Auto-named backup
agentra database --backup
# Custom backup location
agentra database --backup /path/to/backup/agentra-backup.db
Output:
💾 Creating database backup...
✅ Backup created: /home/user/.agentra/backups/agentra-2026-02-23-140532.db
agentra database --migrate
Migrates configuration from file-based storage to database.
agentra database --cleanup
Interactive cleanup:
? Delete old completed sessions? Yes
? Delete sessions older than how many days? 30
🧹 Cleaning up old data...
✅ Cleanup completed:
Sessions deleted: 5
Messages deleted: 89
agentra database --query "SELECT COUNT(*) as total_messages FROM messages"
Output:
🧠 Executing SQL query...
┌─────────────────┐
│ total_messages │
├─────────────────┤
│ 156 │
└─────────────────┘
✅ Query executed successfully.
agentra updateUpdate Agentra to the latest version.
# Update to latest stable
agentra update
# Update to specific release channel
agentra update --channel beta
agentra update --channel dev
Manual update:
npm update -g agentra@latest
agentra doctor # Verify update
# Start all services
agentra gateway --verbose &
agentra run --with-agent --interval 5
# Simple conversation
agentra agent -m "What's my schedule today?"
# Complex analysis
agentra agent -m "Analyze the quarterly sales data and provide insights" --thinking high
# Send results to Telegram
agentra agent -m "Daily summary report" --channel telegram
# Create morning briefing task
agentra task add
# Follow prompts for: schedule, content, target
# Enable/manage tasks
agentra task enable morning-briefing
agentra task list
# Start scheduler
agentra scheduler --verbose
# Set up Telegram bot
agentra channel add telegram
# Enter bot token when prompted
# Start all channels
agentra channel start
# Monitor channel status
agentra channel list
# Daily health check
agentra doctor
# Weekly database backup
agentra database --backup
# Monthly cleanup
agentra database --cleanup
Start gateway and use REST endpoints:
agentra gateway --port 8080
# API endpoints available:
# POST /agent/message - Send message to agent
# GET /channels - List active channels
# GET /health - Health status
# GET /status - System status
# Create daily report task
agentra task add
# Schedule: 0 9 * * 1-5 (weekdays 9 AM)
# Type: agent
# Message: "Generate daily business report"
# Channel: telegram
# Send announcement to all channels
agentra message --to "broadcast" --message "System maintenance tonight"
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ CLI Tools │ │ Gateway │ │ AI Agents │
│ │ │ │ │ │
│ • Commands │◄──►│ • REST API │◄──►│ • Claude │
│ • Interactive │ │ • WebSocket │ │ • GPT │
│ • Scheduling │ │ • WebChat UI │ │ • Gemini │
│ • Health Check │ │ • Session Mgmt │ │ • Conversations │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Channels │ │ Database │ │ Task Scheduler │
│ │ │ │ │ │
│ • Telegram │◄──►│ • SQLite │◄──►│ • Cron Jobs │
│ • WebChat │ │ • Users │ │ • Automation │
│ • Discord* │ │ • Messages │ │ • Monitoring │
│ • Future... │ │ • Sessions │ │ • Health Checks │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Core Components:
# Development mode with auto-reload
npm run dev -- agent -m "test message"
# Watch mode (auto-build on changes)
npm run watch
# Start gateway in development
npm run gateway:watch
# Build for production
npm run build
# Clean build artifacts
npm run clean
agentra/
├── src/
│ ├── cli.ts # Main CLI entry point
│ ├── core/
│ │ ├── agent.ts # AI agent implementation
│ │ ├── config.ts # Configuration management
│ │ └── scheduler.ts # Task scheduling
│ ├── commands/
│ │ ├── onboard.ts # Onboarding wizard
│ │ ├── doctor.ts # Health diagnostics
│ │ └── task.ts # Task management
│ ├── gateway/
│ │ └── server.ts # Gateway server (Express + WebSocket)
│ ├── channels/
│ │ ├── telegram.ts # Telegram integration
│ │ └── manager.ts # Channel management
│ ├── ai/
│ │ ├── anthropic.ts # Claude integration
│ │ ├── openai.ts # GPT integration
│ │ └── gemini.ts # Gemini integration
│ ├── db/
│ │ ├── database.ts # Database operations
│ │ └── repositories/ # Data access layer
│ ├── security/
│ │ └── securityManager.ts # Security & access control
│ └── types/
│ └── index.ts # TypeScript type definitions
├── dist/ # Compiled JavaScript output
├── agentra-workspace/ # User workspace directory
└── package.json # NPM configuration
# Regular security audit
agentra doctor
# Review access logs
agentra database --query "SELECT * FROM sessions WHERE created_at > date('now', '-7 days')"
# Backup encrypted data
agentra database --backup
# Monitor active channels
agentra channel list
# Check if port is in use
netstat -tulpn | grep 18789
# Use different port
agentra gateway --port 3000
# Check permissions
agentra doctor
# Run setup wizard
agentra onboard
# Or add manually
agentra models --add anthropic
# Enter API key when prompted
# Verify configuration
agentra models --list
agentra doctor
# Check bot token validity
agentra channel list
# Restart Telegram channel
agentra channel stop telegram
agentra channel start telegram
# Check logs
agentra gateway --verbose
# Check database health
agentra database --status
# Migrate if needed
agentra database --migrate
# Backup before fixes
agentra database --backup
# Clean up corrupted data
agentra database --cleanup
# Check scheduler status
agentra task list
# Restart scheduler
agentra scheduler --verbose
# Verify task syntax
agentra task status <task-id>
# Comprehensive health check
agentra doctor
# Verbose gateway logs
agentra gateway --verbose
# Database diagnostics
agentra database --stats
# Check configuration
agentra models --list
agentra channel list
When gateway is running (agentra gateway):
# Health check
GET /health
# Returns: {"status": "healthy", "uptime": 3600}
# System status
GET /status
# Returns: {"gateway": "running", "channels": [...], "agent": "ready"}
# Send message to agent
POST /agent/message
# Body: {"message": "Hello", "thinking": "medium"}
# Returns: {"response": "Hi there!", "timestamp": "..."}
# List channels
GET /channels
# Returns: [{"id": "...", "type": "telegram", "status": "running"}]
# Send message via channel
POST /message
# Body: {"to": "+1234567890", "message": "Hello", "channel": "telegram"}
# WebChat interface
GET /
# Returns: HTML WebChat interface
// Connect to WebSocket
const ws = new WebSocket('ws://localhost:18789');
// Send message
ws.send(JSON.stringify({
type: 'message',
content: 'Hello Agentra!'
}));
// Receive responses
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Agent response:', data.content);
};
# Fork and clone repository
git clone https://github.com/yourusername/agentra.git
cd agentra
# Install dependencies
npm install
# Start development environment
npm run dev -- onboard
# TypeScript compilation
npm run build
# Run tests (when available)
npm test
# Lint and format
npm run lint
npm run format
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)ISC License - See LICENSE file for details.
Sai Sree Satya
Built with modern technologies and inspired by the local-first movement:
Special thanks to the open-source community! 🌟
🚀 Built with ❤️ and TypeScript - Local-first, secure, and always ready to help!
agentra agent -m "Write a haiku about TypeScript" --thinking high
agentra gateway --port 18789 --verbose
Then open: http://localhost:18789 for WebChat
agentra doctor
Output:
🏥 Agentra Health Check
1. User Profile
✅ Profile exists
Name: John Doe
2. AI Models
✅ 1 model(s) configured
- anthropic (apikey)
3. Channels
ℹ️ No channels configured (optional)
4. Workspace
✅ Workspace configured
5. Gateway
✅ Gateway configuration
📋 Summary
✅ All systems healthy!
agentra/
├── src/
│ ├── cli.ts # Main CLI entry
│ ├── types/
│ │ └── index.ts # TypeScript types
│ ├── core/
│ │ ├── config.ts # Configuration manager
│ │ └── agent.ts # Agent class
│ ├── gateway/
│ │ └── server.ts # Gateway server (Express + WebSocket)
│ └── commands/
│ ├── onboard.ts # Onboarding wizard
│ └── doctor.ts # Health check
├── dist/ # Compiled output
└── package.json
npm run dev # Run in dev mode (ts-node)
npm run build # Build TypeScript
npm run watch # Watch mode
npm run gateway # Start gateway (dev)
npm run gateway:watch # Auto-reload gateway
npm start # Build + run
# Terminal 1: Watch build
npm run watch
# Terminal 2: Run CLI
npm run dev -- agent -m "Test message"
# Terminal 3: Start gateway
npm run gateway:watch
The gateway exposes a REST API + WebSocket interface:
GET /health # Health check
GET /status # Gateway status
GET /channels # List channels
POST /message # Send message
POST /agent/message # Process agent message
GET / # WebChat UI
Connect to ws://localhost:18789 for real-time messaging.
Agentra connects to real messaging surfaces. Treat inbound DMs as untrusted input.
pairing (unknown senders must be approved)agentra pairing approve <channel> <code>
agentra doctor
Anthropic (Recommended)
OpenAI
# During onboarding
agentra onboard
# Or manually
agentra models --add anthropic
# Enter API key when prompted
Like OpenClaw, Agentra will support:
| Feature | OpenClaw | Agentra |
|---|---|---|
| Multi-channel | ✅ | 🚧 In Progress |
| CLI | ✅ | ✅ |
| Gateway | ✅ | ✅ |
| TypeScript | ✅ | ✅ |
| Onboarding | ✅ | ✅ |
| Voice | ✅ | 🚧 Planned |
| Canvas | ✅ | 🚧 Planned |
| WebChat | ✅ | ✅ |
# Check if port is in use
lsof -i :18789
# Use different port
agentra gateway --port 18790
# Run onboarding again
agentra onboard
# Or add manually
agentra models --add anthropic
agentra doctor
# Follow suggestions
# Update to latest
npm update -g agentra@latest
# Health check after update
agentra doctor
# Update from source
git pull
npm install
npm run build
Sai Sree Satya
ISC © Sai Sree Satya
Inspired by OpenClaw - an amazing personal AI assistant framework.
Built with ❤️ and TypeScript - Local-first, fast, and always-on! 🚀
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Gateway │────│ Agent │────│ Database │
│ │ │ │ │ │
│ • WebChat │ │ • Sessions │ │ • Messages │
│ • REST API │ │ • Tools │ │ • Users │
│ • Session │ │ • AI │ │ • Analytics │
│ Tracking │ │ Providers │ │ • Channels │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└───────────────────┼───────────────────┘
│
┌─────────────┐
│ Channels │
│ │
│ • Telegram │
│ • WebChat │
│ • Future... │
└─────────────┘
FAQs
Agentra – Personal AI Assistant with Multi-Channel Support by Sai Sree Satya
We found that agentra demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.