garudust-org/garudust-agent

당신의 AI 에이전트. 당신의 서버. 당신의 규칙.

Rust로 작성된 자기 개선형 (self-improving) AI 에이전트 런타임(runtime) — 약 10 MB 크기의 바이너리이며, 별도의 런타임 의존성이 없습니다. 터미널에서 채팅하고, 7개 플랫폼에 걸쳐 응답하며, 웹 대시보드를 열거나, 데스크톱 앱을 실행하거나, REST + WebSocket API를 노출할 수 있습니다. 어떤 MCP 서버든 연결할 수 있으며, 환경 변수 하나로 LLM 제공업체를 교체할 수 있습니다. 텔레메트리(telemetry)는 없습니다. 종속성(lock-in)도 없습니다.

01 — 설치 (Install)

curl -fsSL https://raw.githubusercontent.com/garudust-org/garudust-agent/main/scripts/install.sh | sh

macOS & Linux, 모든 아키텍처 (ARM, Raspberry Pi, WSL). Windows: irm .../scripts/install.ps1 | iex

GARUDUST_VERSION으로 재정의 가능

/ GARUDUST_BIN_DIR

.

수동 다운로드 또는 소스 빌드 (Manual download or build from source)

GitHub Releases에서 미리 빌드된 바이너리를 가져오세요:

OS	아키텍처 (Architecture)	바이너리 (Binary)
macOS	Apple Silicon (M1/M2/M3/M4)	garudust-*-aarch64-apple-darwin.tar.gz
...

또는 소스에서 빌드 (Rust 1.87+): git clone https://github.com/garudust-org/garudust-agent && cargo build --release

02 — 설정 (Configure)

garudust setup # 대화형 위저드(interactive wizard) — 제공업체를 선택하고 config.yaml + .env를 작성합니다

또는 ~/.garudust/.env에 키를 직접 설정하세요.

(예: ANTHROPIC_API_KEY=sk-ant-...).
지원되는 모든 키는 LLM Providers를 참조하세요.

03 — 실행 (Run)

garudust # 대화형 TUI
garudust "summarise git log" # 원샷 태스크 (one-shot task)
garudust --hint fast "check this" # 더 저렴한 모델로 라우팅
...

UI와 함께 Garudust를 사용하는 권장 방법은 **네이티브 데스크톱 앱 (native desktop app)**입니다. 에이전트가 프로세스 내에 내장된 (webview 없음, 별도의 서버 없음) 순수 Rust (egui) 앱입니다. 다운로드하여 실행하기만 하면 됩니다.

🍎 macOS ·
🪟 Windows ·
🐧 Linux (AppImage) ·
📦 Debian/Ubuntu (.deb)

macOS는 유니버설 빌드 (Intel + Apple Silicon)입니다. 다른 아키텍처 / 버전: 모든 릴리스

OS	설치 (Install)
macOS	.dmg를 열고, Garudust를 응용 프로그램(Applications)으로 드래그하세요
...

빌드는 아직 코드 서명(code-signed)되지 않았으므로, 처음 실행 시 macOS Gatekeeper (우클릭 →

Open) 및 Windows SmartScreen (추가 정보 → 실행)이 경고를 표시할 수 있습니다. 이는 서명되지 않은 앱에서 발생하는 예상된 동작입니다.

처음 실행 시, Secrets 페이지(또는 ~/.garudust/.env)에서 LLM 키를 설정하세요.
Secrets 페이지는 마스킹(masked) 처리되며 쓰기 전용(write-only)입니다. 에이전트는 앱 내부에서 실행됩니다.

소스에서 빌드하기: cargo run -p garudust-desktop-native --release

(apps/desktop-native/README.md 참조).

브라우저를 선호하시나요? 동일한 UI (Rust/Leptos → WASM)가 web-ui 기능을 통해 서버에서 제공됩니다:

cd web && trunk build --release # 1회성 작업: cargo install trunk + rustup target add wasm32-unknown-unknown
cargo run -p garudust-server --features web-ui --port 3000 # → http://localhost:3000 접속

🪶 매우 작은 점유율 (Tiny footprint) — 약 10 MB의 정적 링크(statically linked) 바이너리, 20 ms 미만의 콜드 스타트(cold start), 런타임 의존성 제로. Docker 없이도 Raspberry Pi에서 실행됩니다.

🧠 자기 개선 (Self-improving) — 모든 세션에 걸쳐 사용자의 선호도와 사실을 기억합니다. 복잡한 다단계 워크플로(workflow) 이후에는 재사용 가능한 기술(skills)을 자동으로 작성합니다. 세션 간 목표(goals)는 완료로 표시할 때까지 주입된 상태로 유지되어, 같은 말을 반복할 필요가 없습니다.

🔀 24개의 LLM 제공업체, 단 한 줄의 설정 — Anthropic, OpenAI, Gemini, Groq, Mistral, DeepSeek, Ollama, AWS Bedrock, vLLM 및 15개 이상의 업체. --hint를 사용하여 작업을 더 저렴한 모델로 라우팅(route)하고, 인증 실패 시 폴백(fallback) 키를 자동으로 교체합니다.

📡 하나의 프로세스 내 7개 플랫폼 — Telegram, Discord, Slack, Matrix, LINE, WhatsApp, Webhook. 플랫폼별 RBAC(역할 기반 액세스 제어), 멘션 게이트(mention gate), 사용자별 세션 격리 — 각 어댑터는 .env에 토큰이 입력되는 즉시 활성화됩니다.

⚡ 병렬 도구 실행 (Parallel tool execution) — 독립적인 도구 호출은 동시에 실행되며, 충돌 가능성이 있는 호출은 키(key)를 기준으로 직렬화(serialized)됩니다. 웹 검색, 파일 I/O, 브라우저 자동화 (CDP), 터미널, RAG, 서브 에이전트 위임 등 15개 이상의 내장 도구를 제공합니다. 어떤 MCP 서버든 연결하거나 모든 언어로 작성된 커스텀 스크립트 도구를 추가할 수 있습니다.

🔒 설계 단계부터 고려된 보안 (Secure by design) — 터미널 도구를 위한 세 가지 샌드박스 (sandbox) 모드를 제공합니다: 호스트 직접 연결 (direct host), Docker 컨테이너, 또는 SSH 원격 호스트 (SSH remote host). 샌드박스 유형에 관계없이 가장 파괴적인 명령에 대해서는 엄격한 차단이 적용됩니다. 승인 모드 (auto / smart / deny)가 파괴적인 작업의 실행을 제어합니다. 모델이 확인하기 전에 모든 도구 출력물에서 비밀 정보 (secrets)가 삭제(redacted)됩니다.

🌐 헤드리스 API (Headless API) — garudust-server는 /chat, /stream 및 WebSocket 엔드포인트를 노출하여 어떤 앱이나 스크립트에도 임베딩할 수 있습니다. Cron 스케줄에 따른 자율 작업은 사용자가 없어도 실행됩니다.

🖥️ 웹 대시보드 및 네이티브 데스크톱 앱 — 브라우저를 위해 바이너리에서 직접 제공되는 Rust/Leptos (WASM) 대시보드 (web-ui 기능)와, 에이전트가 프로세스 내에 내장된 순수 Rust 기반의 네이티브 egui 데스크톱 앱 (DMG / EXE / AppImage / deb)을 제공합니다. JS/TS를 사용하지 않으며, 비밀 정보는 마스킹된 상태로 서버 측에 유지됩니다.

모든 어댑터는 동일한 garudust-server 프로세스에서 실행됩니다. ~/.garudust/.env에 토큰을 설정하면 어댑터가 자동으로 활성화됩니다.

config.yaml에서 providers.default.name을 설정하고, ~/.garudust/.env에 해당하는 키를 설정하세요:

Provider	name	.env key
Anthropic	anthropic	ANTHROPIC_API_KEY
OpenAI	openai	OPENAI_API_KEY
Google Gemini	gemini	GEMINI_API_KEY
Groq	groq	GROQ_API_KEY
Mistral	mistral	MISTRAL_API_KEY
DeepSeek	deepseek	DEEPSEEK_API_KEY
xAI (Grok)	xai	XAI_API_KEY
OpenRouter	openrouter	OPENROUTER_API_KEY
AWS Bedrock	bedrock	AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
Ollama	ollama	(없음 — 사용자 지정 엔드포인트의 경우 url: 추가)
vLLM	vllm	VLLM_API_KEY
ThaiLLM	thaillm	THAILLM_API_KEY
Together AI	together	TOGETHER_API_KEY
Fireworks AI	fireworks	FIREWORKS_API_KEY
Cerebras	cerebras	CEREBRAS_API_KEY
Perplexity	perplexity	PERPLEXITY_API_KEY
Cohere	cohere	COHERE_API_KEY
NVIDIA NIM	nvidia	NVIDIA_API_KEY
Alibaba DashScope	alibaba	DASHSCOPE_API_KEY
ByteDance Doubao	doubao	ARK_API_KEY
Zhipu AI (GLM)	zhipu	ZHIPU_API_KEY
Moonshot (Kimi)	moonshot	MOONSHOT_API_KEY
Baidu ERNIE	baidu	QIANFAN_API_KEY
Any OpenAI-compat	(이름 지정 안 함, 프로필에 url: 설정)	relevant key

Fallback keys: set LLM_FALLBACK_API_KEYS=key2,key3

in .env

— 인증 실패 시 자동으로 순환(rotated).

┌──────────────────────────────────────────────────────────────────────┐
│ bin/garudust (CLI) bin/garudust-server (Daemon) │
└────────────────────┬─────────────────────────┬───────────────────────┘
... 

Secrets → ~/.garudust/.env
. Everything else → ~/.garudust/config.yaml
.

# LLM provider — set one (auto-detected from env when no config.yaml)
ANTHROPIC_API_KEY=sk-ant-... 
# OPENAI_API_KEY=sk-... 
... 

providers:
default:
name: anthropic # 모든 24개 옵션은 위의 LLM Provider 표를 참조하세요
...

전체 설정 참조(cron, MCP, RBAC, 압축 등)는 CONTRIBUTING.md를 참고하세요.

전체 설정 참조(cron, MCP, RBAC, 압축 등)는 CONTRIBUTING.md를 참고하세요.

내장 기능으로 구성이 필요하지 않은 경우:

web_fetch

· web_search

· http_request

· browser

(CDP) · read_file

· write_file

· list_directory

· terminal

· memory

· session_search

· delegate_task

· skill_view

· write_skill

· doc_ingest

· doc_search

Hub — garudust-hub의 커뮤니티 도구 및 스킬:

garudust tool install hash_text # script tool → ~/.garudust/tools/hash_text/
garudust tool install read_qr
garudust skill install weather # Markdown instruction, no subprocess
...

MCP — 모든 Model Context Protocol 서버 연결:

mcp_servers:
- name: filesystem
command: npx
...

사용자 정의 도구(Custom tools) — tool.yaml을 추가하세요.

• 스크립트를 ~/.garudust/tools/<이름>/에 배치합니다.
  . 모든 언어 지원. 예시는 garudust-hub를 참조하세요.

config.yaml의 roles:에서 역할 기반 접근 제어를 수행합니다.
. 사용자가 할당되지 않은 경우, 봇에게 DM을 보낸 첫 번째 사람이 자동으로 admin으로 승격됩니다.

roles:
default_role: member
definitions:
...

런타임 명령어: /whoami
· /join [코드]
· /invite <역할> [최대 사용 횟수]
· /role list|add|approve|remove

프로덕션 환경에서 terminal_sandbox: docker (로컬 컨테이너) 또는 terminal_sandbox: ssh (원격 호스트)를 설정하여 셸 실행을 격리하고, max_delegation_depth: 0으로 설정하여 하위 에이전트 체인을 방지할 수 있습니다.

참고: platform.session_per_user: false로 설정하면 모든 사용자가 하나의 대화 컨텍스트를 공유하게 됩니다. 서버는 시작 시 경고(WARN) 메시지를 기록합니다. 단일 사용자 배포에만 안전합니다.

terminal 도구는 세 가지 실행 백엔드를 지원합니다:

모드	terminal_sandbox	실행 위치	필요 사항
Direct host	none	로컬 머신	없음
Docker container	docker	격리된 컨테이너	Docker 데몬
Remote SSH host	ssh	sshd가 있는 모든 호스트	SSH 키 인증

모든 모드는 동일한 하드라인 블록(fork bomb, rm -rf /, mkfs 등)과 동일한 승인 게이트를 공유합니다. 즉, 샌드박스는 명령이 어디서 실행되는지만 제어합니다.

명령은 시스템 ssh를 통해 전달됩니다.

원격 호스트로 바이너리 (binary)를 전달합니다. 인터넷에 어떤 포트도 노출하지 않고 원격 서버, Raspberry Pi 또는 빌드 머신을 관리하는 데 유용합니다. 에이전트가 외부로 SSH 접속을 시도(SSHes out)하므로, 원격 호스트는 포트 22번만 열려 있으면 됩니다.

설정 필드 (Config fields) (config.yaml 내의 security: 하위 항목):

필드 (Field)	타입 (Type)	기본값 (Default)	설명 (Description)
ssh_host	string	—	필수 항목. 원격 호스트 이름 또는 IP
ssh_user	string	현재 OS 사용자	로그인 사용자 이름
ssh_port	integer	22	SSH 포트
ssh_key_path	path	~/.ssh/id_*	개인 키 (Private key) 파일
ssh_jump_host	string	—	NAT 뒤에 있는 호스트를 위한 ProxyJump 배스천 (bastion) (user@host:port)
ssh_remote_cwd	string	—	모든 명령 앞에 cd <dir> &&를 추가함; 쉘 메타문자가 없는 절대 경로여야 함 (예: /home/pi/scripts)
ssh_options	list	[]	추가적인 -o key=value 플래그 (강화된 기본값 뒤에 추가됨)

환경 변수 오버라이드 (Environment variable overrides) — config.yaml이 필요하지 않음:

GARUDUST_TERMINAL_SANDBOX=ssh
GARUDUST_SSH_HOST=192.168.1.50
GARUDUST_SSH_USER=pi
...

최소 작동 예제 (Minimal working example) — 홈 라우터 뒤에 있는 Raspberry Pi:

security:
  terminal_sandbox: ssh
  ssh_host: "192.168.1.50"
...

배스천 (Bastion) 사용 시 — Pi가 공용 점프 서버를 통해서만 접속 가능한 경우:

security:
  terminal_sandbox: ssh
  ssh_host: "pi.internal"
...

자동으로 적용되는 보안 속성 (Security properties applied automatically):

• BatchMode=yes: 대화형 프롬프트 없음; 키 인증이 거부되면 즉시 실패함
• StrictHostKeyChecking=accept-new: 첫 접촉 시 자동으로 신뢰하며, 변경된 호스트 키는 거부함 (MITM 보호)
• ConnectTimeout을 30초로 제한: 무기한 TCP 대기(hang) 방지
• ServerAliveInterval=10 ServerAliveCountMax=3: 명령 타임아웃이 발생할 때까지 기다리는 대신 약 30초 이내에 끊긴 연결을 감지함
• 명령 전 -- 사용: -로 시작하는 명령이 SSH 플래그로 잘못 읽히는 것을 방지함
• ssh 실행 전 env_clear() 수행: API 키와 비밀 정보가 원격 호스트에 절대 도달하지 않음
• ssh_remote_cwd 적용

사용되기 전에 안전한 절대 경로(absolute path)인지 검증됩니다 — 쉘 메타문자 (shell metacharacters) (;, &, |, `, $, ...)를 포함하는 값은 제외됩니다.

git clone https://github.com/garudust-org/garudust-agent
cd garudust-agent
git config core.hooksPath .githooks # pre-push 체크 활성화 (fmt + tests)
cargo build && cargo test --workspace && cargo clippy --workspace

각 영역에 대한 단계별 가이드: CONTRIBUTING.md

커뮤니티 (Community): Discord · Issues · Discussions · dev.to/garudust

MIT — LICENSE 참조.