Agens is a completely free AI assistant designed to let anyone experience the power of AI without spending a single penny. It is built to run entirely on your own devices (or in the cloud) and connects one smart, central brain to all the interfaces you already use: a modern Web dashboard, a sleek Terminal UI, quick command-line chats, or a Telegram bot.
I built this project to make setting up and running your own personal assistant simple and completely hassle-free—no coding, configuration file editing, or subscription fees required.
Get up and running in a single command:
curl -fsSL https://raw.githubusercontent.com/kayesFerdous/agens/main/scripts/install.sh | bashirm https://raw.githubusercontent.com/kayesFerdous/agens/main/scripts/install.ps1 | iexNote: The installer automatically takes care of environment setups, installing any missing tools, and gets Agens ready for your first chat.
| Always Free & Low Token Cost | Built specifically to help you stay within free-tier API limits. Agens keeps conversation histories short, prunes prompt bloat, and only loads tools you actively turn on. |
| Auto-Recover Rate Limits | Free keys hit rate limits often. If your key hits a rate limit while Agens is answering, it instantly rotates to your next key, provider, or fallback model in-flight so your task finishes seamlessly. |
| One Brain, Any Interface | Switch between the Web dashboard, Terminal UI, quick command-line chats, or a Telegram bot. They all share the same memory, databases, and settings. |
| Safe Command Execution | Agens can run shell commands, write files, and do web lookups. A built-in Safety Mode blocks harmful commands automatically, and it securely collects passwords for root commands locally. |
| Secure By Default | Your API keys are encrypted at rest using industry-grade cryptography. They are decrypted only in memory during active runs and are never stored in plaintext files. |
| Free Live Web Searching | Comes with built-in web search and page reading tools. No paid search API subscriptions required—look up facts and read live URLs completely for free. |
Agens is highly capable and can run shell commands or manage files in your workspace. To keep your system safe, we build security in by default:
- Safety Mode: Hard-blocks dangerous shell command families (such as recursive deletes on system folders or editing core OS files) and dangerous command-chaining.
- Interface-Aware Sudo Policies:
- Terminal UI (Trusted): If a command needs
sudoaccess, the TUI pauses the output and displays a secure popup to collect your password, passing it directly to the system subprocess without ever saving it. - Web & Telegram (Untrusted): All
sudoexecutions are hard-blocked on remote or web channels to prevent security exploits.
- Terminal UI (Trusted): If a command needs
Manage keys, safety modes, and environments easily from your terminal:
| Category | Action | CLI Command |
|---|---|---|
| Run Interfaces | Start Web Dashboard | agens web |
| Start Terminal UI | agens tui |
|
| Chat via Command Line | agens chat "your prompt" |
|
| Launch Telegram Listener | agens telegram |
|
| API Key Manager | Add and Encrypt Key | agens apikey add <label> <provider> <key> |
| List Active Keys | agens apikey list |
|
| Temporarily Disable Key | agens apikey disable <label> |
|
| Enable Disabled Key | agens apikey enable <label> |
|
| Permanently Remove Key | agens apikey remove <label> |
|
| Safety Controls | Turn Safety Mode ON | agens safety on |
| Turn Safety Mode OFF | agens safety off |
|
| Daemon Control | List Running Interfaces | agens interfaces |
| Stop All Running Interfaces | agens shutdown |
Find exactly what you need based on what you are trying to achieve:
- 🚀 First-Time Setup: Detailed native, script-based, and containerized (Docker) setup steps across all operating systems.
- ⚙️ Platform & Key Configuration: How encrypted credentials work, setting up automatic failover models, long-term memory configurations, and token optimizations.
- 🛠️ Custom Tools & Extensions: List of built-in file and web tools, and a simple step-by-step tutorial on writing your own custom tools in Python.
- 💻 Developer Loop & Contributions: Setting up a local workspace, building Vite/Svelte 5 assets, compiling release wheels, and database migrations.
- 🏗️ Under the Hood: Architectural deep dive into ports & adapters layout, SQLite connection concurrency, and event loop cancellation protections.
All interfaces write to the exact same database. Explore the premium, feature-parity interfaces:
Features real-time SSE streaming, interactive model pickers, encrypted key managers, and granular tool controls.
Workspace Chat
|
Streaming Message with Tool Output
|
Decoupled Provider Model Selection
|
Granular Tool Control Panel
|
Designed for developers working in terminal or remote SSH environments, offering full parity with the Web UI.
Interactive TUI Home Dashboard
|
Stateful TUI Chat Session
|
graph TD
Input["User Input<br/>(Web · TUI · Telegram · CLI)"]
Adapter["Interface Adapter<br/>src/interfaces/"]
Agent["Agent Orchestrator<br/>src/agent/agent.py"]
DB[("Local SQLite<br/>src/db/")]
PromptBuilder["Prompt Builder<br/>src/planner/prompt_builder.py"]
LLMClient["LLM Client & Router<br/>src/llm/"]
ToolRegistry["Tool Registry<br/>src/core/registry.py"]
Tools["Tool Execution<br/>src/tools/"]
Input -->|triggers| Adapter
Adapter -->|".chat(message, session_id, channel)"| Agent
Agent -->|loads session history| DB
Agent -->|requests system prompt| PromptBuilder
PromptBuilder -->|reads settings & memories| DB
Agent -->|invokes ReAct loop| LLMClient
LLMClient -->|"chunks / tool_calls"| Agent
Agent -->|routes tool call| ToolRegistry
ToolRegistry -->|executes| Tools
Tools -->|returns result dict| Agent
Agent -->|"yields StreamEvent"| Adapter
Adapter -->|renders live output| Input
Agens is distributed under the MIT License.