Garudust Agent

A self-hostable, self-improving AI agent runtime written in Rust.

Chat from your terminal, connect it to Telegram / Discord / Slack / Matrix / LINE / WhatsApp, or call it over HTTP — all from a single binary. It remembers what you teach it, speaks your language, and gets smarter with every session.

Demo

Why Garudust?

• ~10 MB binary, < 20 ms cold start — single statically-linked binary, no runtime dependencies for local use
• Self-improving — learns your preferences, saves reusable workflows as skills, and corrects itself without being told twice
• Speaks your language — detects Thai, Chinese, Japanese, Arabic, Korean, and more automatically; no configuration needed
• Swap providers with one env var — Anthropic, OpenRouter, AWS Bedrock, Ollama, vLLM, or any OpenAI-compatible endpoint
• Secure by design — Docker sandbox, hardline command blocks, memory-poisoning protection, and automatic secret redaction from tool output
• Runs everywhere — laptop TUI, headless server, Docker, Telegram, Discord, Slack, Matrix, LINE, WhatsApp, HTTP
• Composable — every piece is a separate crate; add a tool, platform, or transport without touching anything else

Install

Pre-built binaries (recommended)

Download from GitHub Releases — no Rust required:

tar -xzf garudust-*.tar.gz
sudo mv garudust garudust-server /usr/local/bin/

Build from source

Requires Rust 1.87+:

git clone https://github.com/garudust-org/garudust-agent
cd garudust-agent
cargo build --release
export PATH="$PATH:$(pwd)/target/release"

Quick Start

garudust setup   # first-time wizard — pick provider, save API key

1 — Interactive TUI

garudust

2 — One-shot

garudust "summarise the git log from the last 7 days into a changelog"

Output goes to stdout. Exit code is 0 on success. Pipe-friendly.

3 — Server / Docker

# Minimal
garudust-server --port 3000

# With Docker
echo "OPENROUTER_API_KEY=sk-or-..." > .env
docker compose up

# Production: sandbox + Telegram bot + daily cron
GARUDUST_TERMINAL_SANDBOX=docker \
GARUDUST_API_KEY=my-secret-token \
TELEGRAM_TOKEN=123:ABC \
GARUDUST_CRON_JOBS="0 9 * * *=Post a morning briefing to Telegram" \
GARUDUST_MEMORY_CRON="0 3 * * *" \
garudust-server --port 3000 --approval-mode smart

CLI Reference

garudust setup                              # first-time wizard
garudust doctor                             # check API key, connectivity, DB
garudust config show                        # print active config
garudust model                              # show current model, prompt for new
garudust model anthropic/claude-opus-4-7   # switch model directly
garudust config set ANTHROPIC_API_KEY sk-ant-...
garudust config set VLLM_BASE_URL http://localhost:8000/v1

Configuration

All persistent settings live in ~/.garudust/config.yaml. Secrets and tokens live in ~/.garudust/.env — run garudust setup to configure them interactively. Both files are loaded securely at startup and never forwarded to subprocesses.

~/.garudust/config.yaml

model: anthropic/claude-sonnet-4-6   # model identifier
provider: anthropic                  # auto-detected from API key if omitted

security:
  terminal_sandbox: docker           # none (default) | docker
  terminal_sandbox_image: ubuntu:24.04
  terminal_sandbox_opts:
    - "--network=none"               # cut outbound network access inside container
    - "--memory=512m"                # cap memory

nudge_interval: 5                    # memory-save reminder every N iterations (0 = off)

mcp_servers:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  - name: postgres
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]

Security

Terminal sandbox

Set terminal_sandbox: docker in config.yaml to run every shell command inside an isolated container (--cap-drop ALL, --pids-limit 256, working directory mounted at /workspace). Requires Docker.

Hardline command blocks

Blocked unconditionally, regardless of approval mode:

Approval modes

Set via GARUDUST_APPROVAL_MODE or --approval-mode.

Memory entries from previous sessions are wrapped in <untrusted_memory> tags to prevent memory-poisoning attacks. API keys are scrubbed from tool output automatically; output is truncated to 50 KB to prevent context flooding.

Memory & Self-Improvement

The agent saves durable knowledge to ~/.garudust/memory/ and loads it at the start of every session — you never need to repeat yourself:

You: always format JSON with 2-space indent
Agent: [saves to memory] Got it — I'll use 2-space indent for JSON from now on.

Configure the memory-save nudge interval with nudge_interval in config.yaml (0 = off).

Skills

Reusable instruction sets stored in ~/.garudust/skills/, hot-reloaded on every call.

~/.garudust/skills/
  git-workflow/SKILL.md
  daily-standup/SKILL.md
  rust-code-review/SKILL.md

The agent scans all skills before every message and loads any that are relevant. It creates and patches skill files automatically when it discovers or corrects a workflow.

Minimal SKILL.md:

---
name: git-workflow
description: Opinionated Git commit and PR workflow
version: 1.0.0
---

Always write conventional commits. Always run tests before pushing.
Open a draft PR first, then mark ready when CI is green.

Headless Server

garudust-server runs the HTTP gateway, all platform adapters, and cron jobs in one process.

garudust-server --anthropic-key sk-ant-... --port 3000

HTTP API

# Blocking
curl -X POST http://localhost:3000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "write a haiku about Rust"}'

# Streaming (Server-Sent Events)
curl -X POST http://localhost:3000/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "explain async/await in 3 sentences"}'

# WebSocket: ws://localhost:3000/chat/ws
# Send: {"message": "your task"}  Receive: text chunks … then {"done":true}

# Health & metrics
curl http://localhost:3000/health
curl http://localhost:3000/metrics   # Prometheus-compatible

Platform Adapters

Set the relevant tokens in ~/.garudust/.env and start garudust-server. Every adapter runs together in the same process.

Telegram — create a bot via @BotFather, copy the token.

Discord — create an app at discord.com/developers, enable Message Content Intent under Bot, copy the token.

Slack — create an app at api.slack.com/apps, enable Socket Mode, add scopes chat:write channels:history im:history, install to workspace.

Matrix — works with any homeserver (matrix.org, Synapse, Dendrite, etc.).

LINE — create a Messaging API channel at developers.line.biz, copy the Channel access token and Channel secret, then set GARUDUST_LINE_PORT (default 3002) and point the webhook URL in LINE console to https://your-host:3002/line.

WhatsApp — create a Meta app at developers.facebook.com, add the WhatsApp product, copy the Access token and Phone number ID. Set GARUDUST_WHATSAPP_PORT (default 3003) and point the webhook URL in Meta console to https://your-host:3003/whatsapp. Optionally set WHATSAPP_APP_SECRET to enable HMAC signature verification.

LLM Providers

Set the relevant key in ~/.garudust/.env, then switch models with garudust model or by setting GARUDUST_MODEL.

Built-in Tools

MCP tools — connect any MCP server by adding it to the mcp_servers list in config.yaml (see Configuration).

Architecture

  garudust (CLI)              garudust-server
  ┌────────────────────┐    ┌─────────────────────────────────────────────┐
  │  TUI / one-shot    │    │  HTTP /chat · /stream · /ws                 │
  │  setup · config    ├──┐ │  Telegram · Discord · Slack · Matrix · LINE · WhatsApp │
  │  doctor · model    │  │ │  Webhook · Cron                             │
  └────────────────────┘  │ └──────────────────────────┬──────────────────┘
                          │                            │
                          └─────────────┬──────────────┘
                                        ▼
                               ┌─────────────────┐
                               │      Agent       │
                               │   run_loop()     │
                               └────────┬─────────┘
                            ┌───────────┴───────────┐
                            ▼                       ▼
              ┌──────────────────────┐  ┌─────────────────────────────────┐
              │      Transport       │  │        ToolRegistry              │
              │  Anthropic           │  │  web_fetch · web_search          │
              │  OpenRouter          │  │  http_request · browser          │
              │  AWS Bedrock         │  │  read_file · write_file          │
              │  Codex               │  │  list_directory · terminal       │
              │  Ollama · vLLM       │  │  memory · user_profile           │
              └──────────────────────┘  │  session_search · delegate_task  │
                                        │  skills · + MCP (external)       │
                                        └─────────────┬───────────────────┘
                                                      │
                                          ┌───────────┴───────────┐
                                          ▼                       ▼
                                ┌──────────────────┐  ┌──────────────────────┐
                                │ FileMemoryStore   │  │      SessionDb       │
                                │ memory/ · skills/ │  │   SQLite + FTS5      │
                                └──────────────────┘  └──────────────────────┘

Crate layout

Contributing

Garudust is designed to be easy to extend — adding a tool, transport, or platform adapter typically touches exactly one crate and takes under 100 lines.

Good first issues

• New tool — wrap any CLI or API as a Tool impl in garudust-tools
• New platform — implement PlatformAdapter (e.g. Signal, WeChat)
• Improve TUI — multi-line input, syntax highlighting, mouse support
• Tests — integration tests, property tests, snapshot tests

git clone https://github.com/garudust-org/garudust-agent
cd garudust-agent
cargo build
cargo test --workspace
cargo clippy --workspace --all-targets -- -W clippy::all -W clippy::pedantic

Read CONTRIBUTING.md for code guidelines, commit conventions, and the full CI checklist.

License

MIT — see LICENSE.