samarthya-bot

Multi-Agent · Autonomous · Privacy-First · Offline-Capable · Cross-Platform · Made in India 🇮🇳

Quick Start · Cross-Platform · Skills · Commands · AI Providers · FAQ · Contribute

🤔 What is SamarthyaBot?

SamarthyaBot (समर्थ्य बोट) is a privacy-first, self-hosted, multi-agent AI operating system that runs entirely on your machine — Windows, macOS, or Linux. Unlike cloud assistants, it keeps your data local, encrypted, and under your control.

It is not just a chatbot — it's a full RPA (Robotic Process Automation) agent that can:

• ✍️ Write code and commit to GitHub
• 🚀 Deploy to servers via SSH (password or PEM key)
• 🌐 Control real browsers with Puppeteer (scrape, click, fill forms)
• 📧 Send real emails via SMTP
• 🇮🇳 Handle Indian workflows — GST, UPI, IRCTC, QR codes, Hindi/Hinglish
• 🧠 Think autonomously with a 20-step ReAct planning loop
• 💬 Chat on Telegram, Discord & a Web Dashboard — with /slash commands
• 🎙️ Understand voice via Groq/Whisper transcription
• 🔌 Extend with plugins — drop a .js file for a new skill

The most feature-rich, self-hosted AI agent that runs identically on all three OSes — with 34 built-in skills, 9 AI providers, and a free fully-offline mode via Ollama.

🖥️ Cross-Platform by Design

SamarthyaBot detects your OS at runtime and adapts every shell command, file path, browser launch, and "open" action accordingly. No more "works on Linux, breaks on Windows."

Capability	🪟 Windows	🍎 macOS	🐧 Linux
Shell execution	cmd.exe	/bin/sh	/bin/sh
Open URL/file/app	start	open	xdg-open
Live terminal streaming	✅ Go worker → Node fallback	✅ Go worker → Node fallback	✅ Go worker
Browser discovery	Chrome / Edge / Brave	Chrome / Chromium / Edge / Brave	Chrome / Chromium / Edge / Brave
Clipboard	clip	pbcopy	xclip / xsel / wl-copy
Port management (CLI)	netstat + taskkill	lsof	lsof / fuser

⚙️ How it works: A single source of truth — backend/services/system/platform.js — resolves OS-specific behaviour. The LLM is also told the exact host OS in its system prompt, so it only emits commands valid for your platform.

🔁 Zero-binary fallback: The optional ultra-fast Go micro-worker streams long commands. If its binary isn't built for your platform, SamarthyaBot transparently falls back to a native Node executor — so heavy DevOps tasks work everywhere, out of the box.

🚀 Quick Start (60 Seconds)

Prerequisites: Node.js 20 LTS · MongoDB (local) Free API keys: Gemini · Ollama (offline)

📦 Install from NPM (recommended)

# 1. Install globally (works on Windows, macOS, Linux)
npm install -g samarthya-bot

# 2. Interactive setup wizard — picks provider, keys, channels
samarthya onboard

# 3. Launch engine + dashboard
samarthya gateway

# 4. (Optional) Expose to internet & link Telegram
samarthya tunnel

🎉 Open http://localhost:5000 for the dashboard.

🛠️ From source (development)

git clone https://github.com/mebishnusahu0595/SamarthyaBot.git
cd SamarthyaBot
npm install
samarthya onboard
npm run start

✨ Core Features

Feature	Description	Status
🖥️ True Cross-Platform	OS auto-detected; commands adapt to Windows/macOS/Linux	✅ Live
🤖 Full RPA Engine	Writes code, commits to GitHub, deploys to VPS	✅ Live
⚡ Live Terminal	Go micro-worker streaming + automatic Node fallback	✅ Live
🌍 SSH Deployments	Remote deploy via password or PEM key from a chat prompt	✅ Live
🕸️ Browser Controller	Puppeteer real DOM — scrape, click, navigate, fill forms	✅ Live
🛡️ Hardened Sandbox	Workspace path enforcement + chained-command blacklist	✅ Live
🧠 Autonomous Planner	20-step ReAct loop with failure recovery & retries	✅ Live
💬 Slash Commands	/status, /tools, /pack, /model on every channel	✅ Live
🔐 Encrypted Memory	AES-256-CBC encrypted local memory in MongoDB	✅ Live
🇮🇳 Indian Localization	GST, UPI, QR codes, IRCTC, Hindi/Hinglish	✅ Live
🛠️ 34 Built-in Skills	Files, web, crypto, translate, QR, currency & more	✅ Live
📱 Telegram + Discord	Two-way bots with webhooks, mentions & voice	✅ Live
🌐 React Dashboard	Dark glassmorphism UI with realtime updates	✅ Live
🔌 Plugin System	Drop a .js file → new AI skill, zero restart	✅ Live
🎙️ Voice (Whisper)	Groq/Whisper transcription for voice notes	✅ Live
💓 Heartbeat Tasks	Periodic autonomous tasks from HEARTBEAT.md	✅ Live

🧰 Skills Catalog (34 Built-in Tools)

📁 Files & System	🌐 Web & Network
file_read · file_write · file_list run_command (OS-aware) devops_execute_stream (live) ssh_deploy open_path (start/open/xdg-open) clipboard_copy (cross-platform) capture_desktop_screenshot system_info schedule_background_task	web_search (DuckDuckGo) weather_info (live) http_request (any REST API) url_shorten ip_geolocate crypto_price currency_convert browser_action (Puppeteer) send_email (SMTP)
🇮🇳 India & Productivity	🔐 Utilities & Security
upi_generate (UPI deep link) qr_generate (QR for UPI/links) gst_reminder translate_text (Hindi & more) calculate · summarize_text note_take · reminder_set calendar_schedule	password_generate (crypto-secure) hash_text (md5/sha1/256/512) base64_tool (encode/decode) timezone_now (world clock) simulate_task (dry-run) 🔌 + unlimited custom plugins

💬 Chat Slash-Commands

Control the agent directly from any channel (Web, Telegram, Discord) — instant, no LLM call:

Command	Action
/help	List all commands
/status	Provider, model, active pack & host OS
/tools /skills	List skills in your current pack
/pack [name]	Show or switch pack (student/business/developer/personal)
/model	Show active AI provider + model
/memory	Count of stored memories
/whoami	Your profile & permissions
/new /clear /reset	Start a fresh conversation
/version	SamarthyaBot version

🧠 Supported AI Providers

Provider	Models	Cost	Best For
Google Gemini	gemini-2.5-flash / pro	🟢 Free tier	Default, great balance
Ollama	Llama 3, Mistral, Dolphin	🟢 Free (local)	100% offline, zero data leakage
Groq	Llama 3.3 70B, Qwen3 32B	🟢 Free tier	Fastest inference
Anthropic	Claude 3.5 Sonnet / Opus	🟡 Paid	Smartest reasoning
OpenAI	GPT-5.2, GPT-5-mini, o3-mini	🟡 Paid	Coding & agentic tasks
DeepSeek	DeepSeek Chat / Coder	🟢 Budget	Affordable coding
Qwen	Qwen Max / Turbo	🟢 Budget	Alibaba's best
OpenRouter	100+ models	🟡 Varies	Access any model
Mistral	Mistral Large 3, Devstral 2	🟡 Paid	EU privacy, code agents

💬 Chat Channels & Integrations

Channel	Setup	Status
📱 Telegram	Bot token + samarthya tunnel	✅ Live
🟣 Discord	Bot token + intents + invite URL	✅ Live
🌐 Web Dashboard	Built-in at http://localhost:5000	✅ Live
📱 WhatsApp	Business API integration	🔜 Coming
💼 Slack	Webhook + App	📋 Planned

📱 Telegram Setup

• Open Telegram → @BotFather → /newbot → copy token
• Add to .env: TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN
• Run samarthya gateway then samarthya tunnel (new terminal). The tunnel auto-sets the webhook. 🚀

🟣 Discord Setup

• https://discord.com/developers/applications → Application → Bot → copy token
• Enable MESSAGE CONTENT INTENT
• Add to .env:

  DISCORD_BOT_TOKEN=YOUR_BOT_TOKEN
  DISCORD_ALLOW_FROM=YOUR_USER_ID
  

• OAuth2 → URL Generator → scope bot → invite → samarthya gateway

🔒 Security & Privacy

SamarthyaBot is defense-in-depth by default:

Layer	What it does
🏠 Local control plane	Runs entirely on your machine — zero cloud dependency
🔐 AES-256-CBC	All memories & secrets encrypted at rest
🛡️ Workspace sandbox	File reads/writes confined to the workspace (RESTRICT_TO_WORKSPACE) — enforced in every file tool
🚫 Command blacklist	Blocks rm -rf, mkfs, dd, fork bombs, format, del /f, remote-shell downloads — per-segment, so echo x && rm -rf / is also blocked
🌐 SSRF guard	http_request rejects non-http(s) schemes; file:// is blocked
🔑 Secret-safe	Generated passwords are never logged or stored
🔌 Offline mode	Ollama = 100% offline, zero data leakage
🚨 Kill switch	samarthya stop — instant shutdown

🧪 Hardened in v2.3.0: the workspace sandbox is now wired into file_read / file_write / file_list, and the command guard validates every segment of chained commands. See SECURITY.md to report issues.

🏗️ Architecture

   Telegram / Discord / WebUI / CLI
                 │
                 ▼
  ┌────────────────────────────────────────────┐
  │          SamarthyaBot Gateway              │
  │           (Control Plane :5000)            │
  ├────────────────────────────────────────────┤
  │  ┌────────────┐ ┌──────────┐ ┌──────────┐  │
  │  │ Slash-Cmds │ │ Planner  │ │ LLM Hub  │  │
  │  │ (instant)  │ │ (ReAct)  │ │ (9 prov) │  │
  │  └────────────┘ └────┬─────┘ └────┬─────┘  │
  │                      │            │         │
  │  ┌───────────────────┴────────────┴──────┐ │
  │  │  Tools Engine (34 skills + plugins)   │ │
  │  └───────────────────┬───────────────────┘ │
  │                      │                      │
  │  ┌───────────┐ ┌─────┴──────┐ ┌──────────┐ │
  │  │ platform  │ │ Go Worker  │ │ Sandbox /│ │
  │  │  helper   │ │  + Node    │ │ Security │ │
  │  │ (OS-aware)│ │  fallback  │ │  guard   │ │
  │  └───────────┘ └────────────┘ └──────────┘ │
  │  ┌───────────┐ ┌────────────┐ ┌──────────┐ │
  │  │ Memory    │ │ Browser    │ │ Heartbeat│ │
  │  │ (AES-256) │ │(Puppeteer) │ │  / Cron  │ │
  │  └───────────┘ └────────────┘ └──────────┘ │
  └────────────────────────────────────────────┘
                 │
                 ▼
        MongoDB (Local, Encrypted)

🔌 Developing Plugins

Give your AI new superpowers — drop a .js file in ~/SamarthyaBot_Files/plugins/:

// weather.js
module.exports = {
  name: 'get_weather',
  description: 'Gets current weather for a city',
  parameters: { city: { type: 'string', required: true } },
  execute: async (args) => {
    const res = await fetch(`https://wttr.in/${args.city}?format=j1`);
    const data = await res.json();
    return {
      success: true,
      result: `${args.city}: ${data.current_condition[0].temp_C}°C`
    };
  }
};

Restart the gateway — the agent can now check weather autonomously! 🌦️

🛠️ CLI Commands

Command	Action
samarthya onboard	Interactive setup wizard
samarthya gateway	Start backend engine + dashboard
samarthya tunnel	Expose to internet & link Telegram
samarthya model	Swap LLM provider/model
samarthya telegram / discord	Configure a channel
samarthya config	View current configuration
samarthya status	Show engine status
samarthya stop / restart	Stop / restart the gateway

🏆 Comparison

	OpenClaw	PicoClaw	SamarthyaBot 🇮🇳
Cross-Platform	✅	✅	✅ OS auto-adapts
Browser Control	❌ / search	❌ search only	✅ Real Puppeteer DOM
Web Dashboard	✅	❌ CLI only	✅ React glassmorphism
Live Terminal	❌	❌ async spawn	✅ Go + Node fallback
Slash Commands	✅	partial	✅ Every channel
Indian Workflows	❌	❌	✅ GST/UPI/QR/IRCTC
Encrypted Memory	❌ plaintext	❌ markdown	✅ AES-256-CBC + Mongo
Built-in Skills	100+ external	skills folder	34 built-in + plugins
SSH Deploy	❌	❌	✅ Password + PEM
Install	moderate	single binary	npm i -g samarthya-bot
AI Providers	many	3-4	9 providers, 20+ models

📊 Real-World Use Cases

• 🧑‍💻 Developers: "Create an Express REST API, push to GitHub, deploy to my VPS."
• 📊 Business: "Calculate 18% GST on ₹50,000, make a UPI QR, email the invoice."
• 🎓 Students: "Summarize the top 5 transformer papers and save notes."
• 🏢 DevOps: "SSH into my server, check disk space, restart nginx if down."
• 🇮🇳 Professionals: "Generate a UPI link for ₹2,500, translate this to Hindi."

🗺️ Roadmap

• True cross-platform (Windows / macOS / Linux auto-detect)
• Go micro-worker + Node fallback
• 34 built-in skills (QR, currency, crypto, translate, hash…)
• Slash-commands on every channel
• Hardened sandbox + command guard
• Full RPA · SSH deploy · Puppeteer browser
• Telegram + Discord + Voice (Whisper)
• WhatsApp Business API
• Slack integration
• Docker Compose deployment
• RAG over local documents
• Multi-user role-based access

🤝 Contributing

PRs welcome! See CONTRIBUTING.md and our Code of Conduct.

git clone https://github.com/mebishnusahu0595/SamarthyaBot.git
cd SamarthyaBot && npm install

⭐ Star History

❓ Frequently Asked Questions

Does it really work on Windows, macOS and Linux?

Yes. SamarthyaBot detects your OS at runtime and adapts every shell command, file path, browser launch and "open" action. The LLM is told your exact OS so it only emits valid commands, and the live-terminal worker falls back to native Node if the Go binary isn't built for your platform.

Is SamarthyaBot free?

Yes — 100% free and open-source under MIT. It supports free providers like Gemini and Ollama (fully offline).

Does it work offline?

Yes. With Ollama, SamarthyaBot runs 100% offline with zero data leakage.

Is my data safe?

Everything runs on your machine. Memories are AES-256-CBC encrypted, file tools are sandboxed to your workspace, and dangerous commands are blocked per-segment.

How do I add a new skill?

Drop a .js file in ~/SamarthyaBot_Files/plugins/ with name, description, parameters, and an execute function. See Developing Plugins.

📄 License

MIT License — free to use, modify, and distribute.

Built with ❤️ in India 🇮🇳 by Bishnu Prasad Sahu

📦 NPM · 🐙 GitHub · 🐛 Report Bug · ✨ Request Feature

_{If SamarthyaBot helps you, please give it a ⭐ — it really helps!}