Garudust Agent

Your AI agent. Your server. Your rules.

A lightweight (~10 MB), self-improving AI agent runtime built in Rust with zero runtime dependencies.
Run it as a native desktop workspace, an interactive terminal CLI, or a headless daemon serving REST, WebSockets, and 7 chat platforms.

⚡ Choose Your Interface

Whether you prefer a desktop application, a fast terminal TUI, or an autonomous server, Garudust is ready out of the box.

Option 1: Native Desktop Workspace (Recommended)

A pure-Rust (egui) desktop app with the agent embedded directly in-process — no Node.js, no WebViews, and no separate background server required. Includes multi-session chat, local document ingestion (RAG), and masked secret management.

⬇️ Download Garudust Desktop (v0.13.9)

Build from source: cargo run -p garudust-desktop-native --release (details in apps/desktop-native/README.md).

Option 2: Terminal CLI

Install the single standalone binary in seconds:

# macOS & Linux (any architecture: x86_64, ARM64, Raspberry Pi, WSL)
curl -fsSL https://raw.githubusercontent.com/garudust-org/garudust-agent/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/garudust-org/garudust-agent/main/scripts/install.ps1 | iex

Quickstart in 3 steps:

# 1. First-time setup wizard (picks provider, configures ~/.garudust/.env)
garudust setup

# 2. Interactive Terminal UI
garudust

# 3. One-shot command execution
garudust "Analyze recent git commits and summarize key changes"
garudust --hint fast "Explain quick sort in 2 sentences"

git clone https://github.com/garudust-org/garudust-agent
cd garudust-agent
cargo build --release --bin garudust --bin garudust-server

Option 3: Headless Daemon & 7 Chat Platforms

Run Garudust as an autonomous background daemon with REST + WebSocket APIs and multi-platform adapters:

garudust-server --port 3000
# or via Docker
docker compose up -d

All adapters run inside the single garudust-server binary. Simply add your bot token in ~/.garudust/.env and the adapter activates immediately with per-user session isolation and RBAC.

🌟 Key Capabilities

• 🪶 Ultra-light & Blazing Fast — ~10 MB static binary, < 20 ms cold start, low RAM footprint. Runs effortlessly on a Raspberry Pi or small VPS without Docker overhead.
• 🧠 Persistent Memory & Autonomous Skills — Saves facts and context in ~/.garudust/memory/ across sessions. Automatically crystallizes multi-step workflows into reusable skill scripts (~/.garudust/skills/).
• 📚 Semantic Hybrid RAG — Ingest documents (PDF, Markdown, text, code) with Vector embeddings + SQLite FTS5 full-text search. Drag-and-drop directly into the desktop app or call doc_ingest.
• 🔀 24+ LLM Providers Supported — Seamlessly switch between Anthropic, OpenAI, Gemini, Groq, Mistral, DeepSeek, Ollama, Bedrock, and local vLLM instances. Automatic key rotation on auth/rate-limit errors.
• ⚡ Parallel Tool Dispatch & MCP — Built-in web search, browser automation (CDP), terminal execution, file system operations, and sub-agent delegation. Compatible with any Model Context Protocol (MCP) server.
• 🔒 Hardened Sandboxing & Security — 3 terminal sandbox backends (direct host, Docker container, or isolated SSH remote host). Approval gates (auto, smart, deny) and automatic secret redaction prevent accidental data leaks.

⚙️ Configuration in 60 Seconds

Garudust keeps secrets in ~/.garudust/.env and preferences in ~/.garudust/config.yaml.

1. ~/.garudust/.env (API Keys & Tokens)

# Pick your primary LLM provider (auto-detected if no config.yaml exists):
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...
# GEMINI_API_KEY=AIza...
# GROQ_API_KEY=gsk_...

# Optional fallback keys (rotated automatically on 429 / auth errors):
LLM_FALLBACK_API_KEYS=key2,key3

# Optional platform tokens (activate automatically when set):
TELEGRAM_TOKEN=123456789:AAFxxx
DISCORD_TOKEN=your-discord-bot-token
SLACK_BOT_TOKEN=xoxb-...

2. ~/.garudust/config.yaml (Preferences & Security)

providers:
  default:
    name: anthropic              # anthropic | openai | gemini | groq | deepseek | ollama | ...
    model: claude-sonnet-4-6

security:
  approval_mode: smart           # auto | smart | deny
  terminal_sandbox: none         # none | docker | ssh

# Route specific prompts to faster/cheaper models (e.g. garudust --hint fast "question")
routing:
  fast: groq/llama-3.1-8b-instant

# Max conversation history pairs retained per session
max_history_pairs: 20

🛠️ CLI Management & Toolsets

# Doctor & Config
garudust doctor                     # Inspect environment, API keys, and health
garudust config show                # Print current active configuration
garudust model                      # View or switch the active LLM model

# Script Tools & Skills (from garudust-hub)
garudust tool list                  # List installed & available community tools
garudust tool install <name>        # Install custom script tool (Python, Bash, Node)
garudust skill list                 # List installed & available reusable skills
garudust skill install <source>     # Install skill from hub, GitHub, or URL

🤝 Contributing & Extending Garudust

Garudust is designed to be modular and easy to hack on. Whether you write Rust, Python, Bash, or want to improve documentation, there is a clear place for you:

How You Can Contribute

Developer Setup

# 1. Clone the repository
git clone https://github.com/garudust-org/garudust-agent.git
cd garudust-agent

# 2. Enable pre-push hooks (fmt, clippy, unit tests)
git config core.hooksPath .githooks

# 3. Build workspace and run test suite
cargo check --workspace
cargo test --workspace
cargo clippy --workspace

For step-by-step guides on adding tools, architecture diagrams, and coding standards, read CONTRIBUTING.md.

💬 Community & Support

• Discord: Join the Garudust Community to chat with maintainers and other users.
• GitHub Discussions: Share ideas, workflows, and show off your agent skills on Discussions.
• Issue Tracker: Report bugs or propose new features via Issues. Look for good first issue to get started!

👥 Contributors

Thanks to everyone who contributes to making Garudust better!

📜 License

Distributed under the MIT License. See LICENSE for details.