r/local/bin/

Verify installation

garudust --version garudust-server --version

**Architecture Rationale:** Static linking against musl ensures the binary runs identically across Alpine, Debian, and RHEL-based distributions. This eliminates glibc version conflicts and simplifies containerization or bare-metal deployment.

### 2. LINE Messaging API Provisioning

LINE's webhook architecture requires explicit channel creation and cryptographic credential generation. Navigate to the LINE Developers Console, create a new Provider, and provision a Messaging API channel. Extract the Channel Secret and generate a long-lived Channel Access Token. Enable the webhook toggle immediately to prevent silent delivery failures.

Store these credentials securely. They will be injected at runtime via environment variables, never committed to version control.

### 3. Configuration Architecture & Secret Isolation

Garudust enforces a strict separation between behavioral configuration and sensitive credentials. This prevents accidental exposure in CI/CD pipelines or public repositories.

Create the runtime directory:
```bash
mkdir -p ~/.garudust
chmod 700 ~/.garudust

Secrets File (~/.garudust/.env)

# Inference Provider Credentials
PROVIDER_API_KEY=sk-ant-apikey-placeholder

# Messaging Transport Credentials
TRANSPORT_CHANNEL_SECRET=ln-ch-secret-placeholder
TRANSPORT_CHANNEL_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.placeholder

Behavioral Configuration (~/.garudust/config.yaml)

inference:
  provider: anthropic
  model: claude-sonnet-4-6
  temperature: 0.7
  max_tokens: 1024

system_instruction: |
  You are an autonomous assistant operating on a messaging platform.
  Respond concisely in Thai. Prioritize factual accuracy and structured formatting.
  Decline requests involving harmful, illegal, or explicit content.

transports:
  line_adapter:
    active: true
    listen_port: 3002
    endpoint_route: /messaging-hook

Why this structure works: The YAML file defines topology and routing. The ENV file defines identity. This aligns with the Twelve-Factor App methodology and enables seamless secret rotation without restarting the agent process. The framework automatically binds the specified port and route, eliminating manual Express/Fastify boilerplate.

4. Webhook Routing & TLS Termination

LINE mandates HTTPS for webhook delivery. The routing strategy diverges based on environment topology.

Development Topology (Localhost) Use a secure tunnel to expose the local port:

ngrok http 3002

Register the generated HTTPS URL + /messaging-hook in the LINE Console. Verify the endpoint. The framework handles signature validation automatically when the secret is present in the ENV file.

Production Topology (Public VPS) Deploy Nginx as a TLS terminator and reverse proxy. This offloads certificate management and connection pooling from the agent binary.

server {
    listen 443 ssl http2;
    server_name agent.yourdomain.io;

    ssl_certificate     /etc/letsencrypt/live/agent.yourdomain.io/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/agent.yourdomain.io/privkey.pem;

    # Transport adapter routing
    location /messaging-hook {
        proxy_pass http://127.0.0.1:3002;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Core API & health endpoints
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
    }
}

Architecture Decision: Nginx handles HTTP/2 multiplexing, gzip compression, and connection keep-alives. The Rust binary focuses exclusively on inference routing and state management. This separation improves observability and allows independent scaling of the proxy layer.

5. Process Supervision & Auto-Restart

Production agents require resilience against OOM kills, network partitions, and upstream API failures. Systemd provides native process supervision, logging, and environment injection.

# /etc/systemd/system/messaging-agent.service
[Unit]
Description=Autonomous Messaging Agent Runtime
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=agent-runner
Group=agent-runner
ExecStart=/usr/local/bin/garudust-server
Restart=on-failure
RestartSec=5
EnvironmentFile=/home/agent-runner/.garudust/.env
WorkingDirectory=/home/agent-runner
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Enable and launch:

sudo systemctl daemon-reload
sudo systemctl enable --now messaging-agent
journalctl -u messaging-agent -f

6. Custom Webhook Signature Verification (TypeScript Example)

While the framework handles validation internally, custom integrations or middleware layers may require explicit signature verification. The following TypeScript utility demonstrates how to validate LINE's X-Line-Signature header using the channel secret.

import { createHmac, timingSafeEqual } from 'crypto';

export function verifyLineSignature(
  rawBody: string,
  signature: string,
  channelSecret: string
): boolean {
  const expectedHash = createHmac('sha256', channelSecret)
    .update(rawBody, 'utf8')
    .digest('base64');

  // Constant-time comparison to prevent timing attacks
  const expectedBuffer = Buffer.from(expectedHash, 'base64');
  const receivedBuffer = Buffer.from(signature, 'base64');

  if (expectedBuffer.length !== receivedBuffer.length) {
    return false;
  }

  return timingSafeEqual(expectedBuffer, receivedBuffer);
}

Why this matters: Webhook endpoints are publicly accessible. Without signature verification, attackers can forge messages, trigger unintended tool execution, or exhaust LLM quotas. Constant-time comparison mitigates side-channel attacks.

Pitfall Guide

1. Credential Leakage in Configuration Files

Explanation: Embedding API keys or channel secrets directly in config.yaml or committing them to Git exposes infrastructure to unauthorized access. Fix: Strictly isolate secrets in .env files with 600 permissions. Use .gitignore rules and pre-commit hooks to scan for patterns like sk-ant-, eyJhbGci, or ln-ch-.

2. Webhook Verification Bypass

Explanation: Disabling signature validation or using placeholder secrets allows malicious actors to inject payloads directly into the agent runtime. Fix: Never run the agent in production without a valid channel secret. Implement middleware that rejects requests missing the X-Line-Signature header before they reach the inference pipeline.

3. Port Binding Conflicts

Explanation: Multiple services attempting to bind to 0.0.0.0:3002 cause silent startup failures or routing misdirection. Fix: Use ss -tlnp | grep 3002 to audit port usage before deployment. Configure the framework to fail fast with explicit error codes if the port is occupied, rather than falling back to a random port.

4. Cron Syntax Misalignment

Explanation: The built-in scheduler uses standard cron notation. Misplaced spaces or invalid day-of-week values cause silent job drops. Fix: Validate expressions using crontab -T or online validators before injecting into the ENV file. Test with a 1-minute interval (* * * * *) before scheduling production jobs.

5. Ignoring Message Type Routing

Explanation: LINE delivers text, image, sticker, and location events. Assuming all payloads are text causes parsing errors and failed inference calls. Fix: Implement type guards in your system prompt or tool definitions. Filter non-text events at the adapter layer or route them to specialized handlers (e.g., OCR for images, geocoding for locations).

6. Memory Accumulation in Long Sessions

Explanation: Unbounded conversation history grows linearly, increasing token costs and latency. Eventually, it exceeds context windows or triggers OOM conditions. Fix: Implement sliding window truncation or semantic summarization. Use the built-in memory cron (GARUDUST_MEMORY_CRON) to periodically compress session state into vector embeddings or concise summaries.

7. SSL/TLS Termination Misconfiguration

Explanation: Nginx proxying to the agent without forwarding X-Forwarded-Proto causes redirect loops or insecure cookie flags. Fix: Always propagate X-Forwarded-Proto $scheme and X-Forwarded-For $proxy_add_x_forwarded_for. Verify that the agent runtime respects forwarded headers for URL generation and security policies.

Production Bundle

Action Checklist

• Provision LINE Messaging API channel and extract Channel Secret + Access Token
• Create ~/.garudust/ directory with restricted permissions (chmod 700)
• Populate .env with provider keys and transport credentials only
• Define config.yaml with inference parameters, system instructions, and adapter ports
• Verify webhook endpoint using ngrok (dev) or Nginx + Let's Encrypt (prod)
• Register HTTPS webhook URL in LINE Console and trigger verification
• Deploy systemd service file and enable auto-restart on failure
• Configure memory compression cron and validate token usage metrics
• Implement log rotation (logrotate) for /var/log/garudust/ output
• Run load test with concurrent messages to validate rate limiting and queue depth

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Internal team prototyping	ngrok + local binary	Zero infrastructure setup, instant iteration	$0
Public-facing customer bot	VPS + Nginx + systemd	TLS termination, process supervision, high availability	$5–$10/mo
Multi-channel deployment (LINE + WhatsApp)	Single binary, multi-adapter config	Shared inference pipeline, isolated transport ports	$5–$15/mo
High-volume enterprise (>50k msgs/day)	Containerized + auto-scaling group	Horizontal scaling, resource isolation, observability	$40–$120/mo
Strict data residency (on-prem)	Ollama/vLLM + local binary	Zero external API calls, full control over weights	Hardware + electricity

Configuration Template

Copy this structure into your deployment environment. Adjust ports, routes, and model parameters to match your topology.

# ~/.garudust/config.yaml
inference:
  provider: anthropic
  model: claude-sonnet-4-6
  temperature: 0.6
  max_tokens: 1500
  timeout_seconds: 30

system_instruction: |
  Operate as a secure, autonomous assistant. 
  Format responses using markdown. 
  Refuse unsafe or ambiguous requests. 
  Maintain conversation context within token limits.

transports:
  line_adapter:
    active: true
    listen_port: 3002
    endpoint_route: /webhook/line
  generic_hook:
    active: false
    listen_port: 3001
    endpoint_route: /webhook/generic

observability:
  log_level: info
  metrics_port: 3000
  health_endpoint: /status
  request_timeout: 25

# ~/.garudust/.env
PROVIDER_API_KEY=sk-ant-your-key-here
TRANSPORT_CHANNEL_SECRET=ln-ch-your-secret-here
TRANSPORT_CHANNEL_TOKEN=eyJhbGci-your-token-here
GARUDUST_MEMORY_CRON=0 3 * * *
GARUDUST_CRON_JOBS=0 8 * * 1-5=Generate daily briefing and save to ~/reports/daily.md

Quick Start Guide

1. Install the runtime: Download the latest musl-static binary for your OS and place it in /usr/local/bin/. Verify with garudust-server --version.
2. Provision credentials: Create a LINE Messaging API channel. Copy the Channel Secret and Access Token. Generate an Anthropic or OpenAI API key.
3. Initialize configuration: Create ~/.garudust/.env with your keys. Create ~/.garudust/config.yaml with your model, system prompt, and adapter port (3002).
4. Expose the endpoint: Run ngrok http 3002 for local testing, or configure Nginx with SSL for production. Register the HTTPS URL + /webhook/line in the LINE Console.
5. Launch & verify: Execute garudust-server. Send a test message to your LINE Official Account. Confirm the response appears within 1–2 seconds. Monitor logs with journalctl -u messaging-agent -f or console output.

This architecture delivers a production-ready, self-hosted messaging agent with deterministic performance, explicit security boundaries, and zero vendor lock-in. By treating the transport layer as a pluggable adapter and the inference pipeline as a configurable service, you retain full control over cost, compliance, and customization while eliminating months of boilerplate development.