ust-x86_64-unknown-linux-musl.tar.gz tar -xzf garudust-*.tar.gz sudo mv garudust garudust-server /usr/local/bin/

Verify installation

garudust --version

For Apple Silicon environments:

```bash
curl -LO https://github.com/garudust-org/garudust-agent/releases/latest/download/garudust-aarch64-apple-darwin.tar.gz
tar -xzf garudust-*.tar.gz
sudo mv garudust garudust-server /usr/local/bin/

Architecture Rationale: Static linking eliminates glibc compatibility issues and ensures identical behavior across Linux distributions. The ~10 MB footprint allows deployment on minimal containers or edge devices without storage penalties.

Step 2: Bind the LLM Provider

The runtime delegates inference to external providers. Configuration is handled via environment variables or an interactive setup wizard.

# Interactive configuration
garudust setup

# Direct environment binding
export ANTHROPIC_API_KEY="sk-ant-api-03..."
export GARUDUST_MODEL="anthropic/claude-sonnet-4-6"

# Alternative: OpenRouter for model routing
export OPENROUTER_API_KEY="sk-or-route-..."
export GARUDUST_MODEL="openrouter/anthropic/claude-3.5-sonnet"

# Alternative: Local inference via vLLM
export VLLM_BASE_URL="http://127.0.0.1:8000/v1"
export GARUDUST_MODEL="Qwen/Qwen3-8B-AWQ"

# Alternative: Ollama for fully local execution
export OLLAMA_BASE_URL="http://127.0.0.1:11434"
export GARUDUST_MODEL="llama3.2"

Validate connectivity and provider routing:

garudust doctor
garudust "Verify provider routing and token limits."

Architecture Rationale: Provider abstraction prevents vendor lock-in. The runtime normalizes API responses across Anthropic, OpenRouter, vLLM, and Ollama, allowing seamless fallback routing or cost optimization without code changes.

Step 3: Define the Execution Skill

Skills are Markdown files containing structured instructions, formatting rules, and tool routing hints. They reside in a dedicated directory and are hot-reloaded on every invocation.

mkdir -p ~/.config/garudust/skills/ops-digest

Create the skill definition:

---
name: ops-digest
description: Generates a structured morning operations briefing
version: 2.1.0
---

## Output Structure
1. **Header**: Current timestamp and operator identifier
2. **Priority Queue**: 2-3 actionable items derived from memory or log analysis
3. **Metrics Snapshot**: Aggregate statistics from ~/ops-data/ (requests, latency, error count)
4. **Closing**: Context-aware sign-off, never repetitive

## Formatting Constraints
- Maximum payload: 280 words
- Use plain text with minimal markdown (*bold*, _italic_)
- Omit metrics section if source files are missing or empty
- Append signature: "Systems nominal. Proceed."

## Tool Routing
- Use `read_file` for ~/ops-data/app.log and ~/ops-data/crash.log
- Parse timestamps relative to last execution cycle
- Suppress stack traces; extract only error codes and frequencies

Architecture Rationale: Hot-reloading skills eliminates restart cycles during prompt iteration. The frontmatter enables version tracking and conditional loading. Separating instructions from runtime logic allows non-developers to modify agent behavior without touching configuration files.

Step 4: Configure Deterministic Scheduling

The runtime includes a native cron parser. Jobs are defined as environment variables mapping cron expressions to natural language tasks.

export GARUDUST_CRON_JOBS="0 9 * * *=Generate ops-digest briefing and deliver via Telegram"

Multiple schedules can be chained:

export GARUDUST_CRON_JOBS="0 9 * * *=Generate ops-digest briefing,0 17 * * 5=Compile weekly incident summary"

Architecture Rationale: Native cron integration removes dependency on external schedulers (systemd timers, Kubernetes CronJobs, or cloud functions). The runtime resolves relative time, handles timezone normalization, and guarantees idempotent execution.

Step 5: Initialize the Daemon

Consolidate configuration into a dotenv file for production stability.

# ~/.config/garudust/daemon.env
ANTHROPIC_API_KEY=sk-ant-api-03...
GARUDUST_MODEL=anthropic/claude-sonnet-4-6
GARUDUST_CRON_JOBS="0 9 * * *=Generate ops-digest briefing and deliver via Telegram"
GARUDUST_APPROVAL_MODE=auto
RUST_LOG=warn
TELEGRAM_TOKEN=7123456789:AAHxxx...

Launch the server:

set -a; source ~/.config/garudust/daemon.env; set +a
garudust-server --port 3000

Expected initialization logs:

INFO garudust_server: Binding to 0.0.0.0:3000
INFO garudust_platforms::telegram: Gateway authenticated
INFO garudust_cron: Registered job "0 9 * * *" → Generate ops-digest briefing
INFO garudust_memory: Persistent store initialized at ~/.config/garudust/state.db

Architecture Rationale: The daemon architecture separates scheduling, platform routing, and state management into isolated modules. This enables horizontal scaling of specific components if needed, while maintaining a single binary for deployment.

Step 6: Client Integration (TypeScript)

For programmatic triggering or streaming responses, use the HTTP gateway.

import { fetch } from 'undici';

async function triggerDigest() {
  const response = await fetch('http://localhost:3000/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      message: 'Execute ops-digest skill immediately',
      stream: false
    })
  });

  const payload = await response.json();
  console.log('Agent response:', payload.content);
}

async function streamLogAnalysis() {
  const response = await fetch('http://localhost:3000/chat/stream', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      message: 'Analyze crash.log for recurring patterns',
      stream: true
    })
  });

  const reader = response.body?.getReader();
  if (!reader) return;

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    process.stdout.write(new TextDecoder().decode(value));
  }
}

Architecture Rationale: Streaming endpoints reduce memory pressure during long-running tool executions. The TypeScript client demonstrates how external systems can inject tasks without waiting for cron cycles, enabling event-driven agent workflows.

Pitfall Guide

1. Skill Frontmatter Syntax Errors

Explanation: The runtime parses YAML frontmatter to load skills. Missing dashes, incorrect indentation, or unescaped quotes cause silent load failures. Fix: Validate frontmatter with a YAML linter before deployment. Use garudust skills list to verify successful registration. Keep frontmatter minimal; move complex instructions to the body.

2. Cron Timezone Drift

Explanation: Cron expressions default to the system timezone. Servers in UTC executing jobs for users in EST will trigger at incorrect local times. Fix: Explicitly set TZ=America/New_York in the environment file. Verify with date inside the daemon container. Use GARUDUST_CRON_TZ if supported, or normalize timestamps in the skill definition.

3. Memory Context Window Saturation

Explanation: Persistent memory accumulates across sessions. Without pruning, the context window fills with outdated preferences, degrading inference quality and increasing token costs. Fix: Implement periodic memory compaction. Use garudust memory prune --days 30 or configure GARUDUST_MEMORY_TTL=720h in the environment. Structure skills to reference memory keys rather than dumping full history.

4. Hot-Reload File Lock Conflicts

Explanation: Editing a skill file while the daemon is actively reading it can cause partial loads or parse errors. Fix: Write to a temporary file and use mv for atomic replacement. Avoid editing skills during peak execution windows. Monitor RUST_LOG=debug for file watcher events.

5. API Key Rotation Blind Spots

Explanation: Hardcoded keys in dotenv files or environment variables persist until daemon restart. Rotating keys without restarting leaves the agent using expired credentials. Fix: Use a secrets manager (HashiCorp Vault, AWS Secrets Manager) with short-lived tokens. Implement a health check endpoint that validates provider connectivity and triggers graceful reload on 401 responses.

6. Over-Delegating Tool Calls

Explanation: Skills that instruct the agent to read every file in a directory or fetch unbounded logs cause tool recursion and timeout failures. Fix: Constrain tool parameters in skill definitions. Use glob patterns with depth limits (~/ops-data/*.log instead of ~/ops-data/**). Implement retry budgets and explicit error handling in the skill body.

7. Platform Gateway Rate Limiting

Explanation: Telegram, Discord, and Slack enforce strict message rate limits. Burst cron executions or streaming responses can trigger temporary bans. Fix: Implement exponential backoff in the platform adapter configuration. Queue messages during rate limit windows. Use GARUDUST_PLATFORM_RATE_LIMIT=1000 to throttle outbound payloads.

Production Bundle

Action Checklist

• Verify binary integrity: Run sha256sum against release checksums before deployment
• Isolate skill directory: Mount ~/.config/garudust/skills/ as a read-only volume in containers
• Configure log rotation: Set RUST_LOG=warn and rotate daemon logs every 24 hours
• Validate cron syntax: Test expressions with garudust cron validate before binding
• Implement health checks: Expose /health endpoint and monitor provider connectivity
• Backup state database: Schedule daily snapshots of ~/.config/garudust/state.db
• Rotate API keys: Integrate with secrets manager and automate credential refresh
• Audit skill versions: Track frontmatter version fields and rollback on regression

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Low-traffic internal bot	Local Ollama + static binary	Zero API costs, full data locality	$0/month, higher RAM usage
High-frequency scheduling	Anthropic Sonnet + native cron	Predictable latency, token-efficient	~$15-30/month depending on volume
Multi-platform routing	OpenRouter + Telegram/Discord adapters	Model fallback, unified billing	~$20-50/month, scales with message count
Edge/constrained hardware	vLLM + Qwen3-8B-AWQ	Quantized model, <4GB RAM footprint	Hardware cost only, no API fees
Enterprise compliance	Self-hosted vLLM + air-gapped skills	Data never leaves infrastructure	Infrastructure + maintenance overhead

Configuration Template

# ~/.config/garudust/production.env
# Core Runtime
GARUDUST_MODEL=anthropic/claude-sonnet-4-6
GARUDUST_APPROVAL_MODE=auto
RUST_LOG=warn

# Provider Credentials
ANTHROPIC_API_KEY=sk-ant-api-03-production...
TELEGRAM_TOKEN=7123456789:AAHxxx-production...

# Scheduling
GARUDUST_CRON_JOBS="0 9 * * *=Generate ops-digest briefing,0 17 * * 5=Compile weekly incident summary"
GARUDUST_CRON_TZ=America/New_York

# Memory & State
GARUDUST_MEMORY_TTL=720h
GARUDUST_STATE_PATH=/var/lib/garudust/state.db

# Platform Limits
GARUDUST_PLATFORM_RATE_LIMIT=1000
GARUDUST_MAX_TOOL_RETRIES=3

Quick Start Guide

1. Download & Verify: Fetch the static binary for your architecture, verify checksums, and place it in /usr/local/bin/.
2. Bind Provider: Export your LLM API key and model identifier. Run garudust doctor to confirm routing.
3. Define Skill: Create a Markdown file in ~/.config/garudust/skills/ with frontmatter and formatting rules.
4. Launch Daemon: Source the environment file and start garudust-server --port 3000. Verify cron registration in logs.
5. Test Execution: Trigger the skill via HTTP POST or wait for the scheduled cron window. Iterate on skill formatting using hot-reload.