# MikroClaw
> Ultra-lightweight AI agent runtime for MikroTik RouterOS container deployments.

## Overview
MikroClaw is a sub-200KB C binary AI agent runtime designed for MikroTik RouterOS containers. It provides LLM-powered automation with VPN-first security, memU cloud memory, and 14 registered function tools.

## Source Code
- Repository: https://github.com/mikroclaw/mikroclaw
- License: See repository

## Quick Start
```bash
export BOT_TOKEN="your_telegram_bot_token"
export OPENROUTER_KEY="your_openrouter_key"
export ROUTER_HOST="192.168.88.1"
export ROUTER_USER="admin"
export ROUTER_PASS="your_password"
make clean && make
./mikroclaw agent
```

## Gateway API (port 18789)
- GET /health - Component health status
- GET /health/heartbeat - Lightweight heartbeat probe
- POST /pair - Exchange X-Pairing-Code header for bearer token
- POST /tasks - Submit task to subagent runtime (body requires "type")
- GET /tasks - List all queued tasks
- GET /tasks/:id - Get task status/result
- DELETE /tasks/:id - Cancel a task

## Function Tools (14 registered)

### Memory
- memory_store(key, value) - Store key/value memory via memU cloud
- memory_recall(key) - Recall key memory from memU cloud
- memory_forget(key) - Forget key memory from memU cloud

### Network
- web_search(query) - Search web documents
- web_scrape(url) - Scrape URL via cloud services
- parse_url(url) - Parse URL host/path

### RouterOS
- routeros_execute(command) - Execute RouterOS command via REST API
- shell_exec(command) - Execute allowed shell command (constrained by ALLOWED_SHELL_CMDS)

### Filesystem
- file_read(path) - Read file in workspace (enforces workspace checks, forbidden paths, symlink escape prevention)
- file_write(path, content) - Write file in workspace

### Skills
- skill_list() - List skills directory entries
- skill_invoke(skill, params?) - Invoke executable skill from skills directory

### System
- health_check() - Return process health
- composio_call(tool, input) - Call Composio-compatible endpoint

## LLM Providers (13 supported)
Provider registry with reliable fallback chains. Includes: OpenRouter, OpenAI, Anthropic, Ollama, and 9 more.

## Channels
- Telegram (polling + send + allowlist)
- Discord (webhook + allowlist)
- Slack (webhook + allowlist)
- Gateway API (direct HTTP)

## Security
- Pairing-token authentication
- Per-IP rate limiting + auth lockout
- Per-channel sender allowlists
- Workspace-only file path enforcement
- Forbidden path defaults + symlink escape prevention
- Encrypted secrets (ENCRYPTED:v1:... format)

## Architecture Layers
1. Core Runtime: main.c, mikroclaw.c, cli.c, log.c
2. LLM + Providers: llm.c, llm_stream.c, provider_registry.c
3. Tooling + Execution: functions.c, task_queue.c, worker_pool.c, subagent.c
4. Gateway + Security: gateway.c, gateway_auth.c, rate_limit.c
5. Channel Layer: telegram.c, discord.c, slack.c, allowlist.c

## CLI Commands
- ./mikroclaw agent - Run AI agent loop
- ./mikroclaw gateway [--port 0] - Start HTTP gateway
- ./mikroclaw daemon - Run as background daemon
- ./mikroclaw status - Check runtime status
- ./mikroclaw doctor - Diagnose configuration issues
- ./mikroclaw channel - Test channel connectivity
- ./mikroclaw config --dump - Dump current configuration
- ./mikroclaw integrations [list|info <name>] - List or inspect integrations
- ./mikroclaw identity [--rotate] - Manage device identity
- ./mikroclaw encrypt KEY=VALUE - Encrypt secret values

## Build Targets
- make: dynamic binary (mikroclaw)
- make static-musl: fully static binary (mikroclaw-static-musl)
- make mikrotik-docker: RouterOS container binary

## Key Environment Variables
- LLM_PROVIDER, LLM_BASE_URL, LLM_API_KEY, RELIABLE_PROVIDERS
- MEMU_API_KEY, MEMU_BASE_URL, MEMU_DEVICE_ID
- ROUTER_HOST, ROUTER_USER, ROUTER_PASS
- GATEWAY_PORT, GATEWAY_BIND, PAIRING_REQUIRED
- BOT_TOKEN, DISCORD_WEBHOOK_URL, SLACK_WEBHOOK_URL
- ALLOWED_SHELL_CMDS, FORBIDDEN_PATHS