oxicrab - Multi-Channel AI Assistant Framework for Rust

Features

Built for real-world AI agents

Everything you need to deploy autonomous assistants. Async-first, security-hardened, built from the ground up in Rust.

Multi-Channel

Five platforms, one codebase

Telegram, Discord, Slack, WhatsApp, Twilio SMS/MMS. Each is a Cargo feature flag — compile only what you deploy.

LLM Providers

Anthropic, OpenAI, Google, and OpenAI-compatible

Claude, GPT, Gemini natively, plus OpenRouter, DeepSeek, Groq, Ollama, Moonshot, Zhipu, DashScope, MiniMax, and vLLM via OpenAI-compatible adapter. OAuth support and automatic provider selection by model name.

Routing Layers

Deterministic first, constrained LLM second, full LLM last

Messages route through strict policy layers: direct dispatch for rules, buttons, and directives; constrained LLM turns with exact tool allow/block lists; then full LLM fallback with semantic tool narrowing when confidence is high. Session metadata persists tool-focused context and replay traces.

Long-Term Memory

SQLite-backed memory with optional hybrid vector search

SQLite-backed memory with automatic fact extraction from conversations, optional hybrid vector+keyword search via local ONNX embeddings, and configurable fusion strategies. Quality gates filter low-signal content and reframe negative memories before persistence.

30 Built-in Tools

Filesystem, shell, web, browser, and more

Every tool has timeout protection, panic isolation via tokio::spawn, result caching, binary blob sanitization, and truncation middleware. Parallel tool execution via concurrency classification (read-only tools run concurrently, side-effect tools sequential, exclusive tools alone). Plus MCP for external tool servers.

Subagents

Parallel background task execution

Capability-based tool access (full, read-only, or denied per tool), semaphore-based concurrency control, context injection from compaction summaries, silent mode for daemon tasks, and lifecycle management.

Sessions

Persistent sessions with automatic compaction

Per-channel session management with context summarization. Long conversations are automatically compacted to stay within context limits while preserving key information. Orphaned tool messages are cleaned up post-compaction to prevent API errors. Per-session message queuing coalesces messages arriving during an active agent run (max 10 per session). Pre-flight token estimation trims oldest messages before LLM calls to prevent wasted API calls.

Hallucination Detection

Catches false claims and phantom actions

Action claim detection, false no-tools-claim retry, false-claim regex detection, intent-based structural analysis, and wrap-up nudges. Prevents the agent from claiming it did something it didn’t.

Auto-Continue

Automatic task completion

When the agent stops mid-task (after 3+ tool calls with iteration budget remaining), it automatically re-prompts to continue (up to 2 times). Prevents incomplete multi-step workflows.

Status Messages

Live tool progress in a single editable message

Tool execution progress shown as a single message that edits in-place (Telegram, Discord, Slack). Includes typing indicator and automatic cleanup on completion.

Connection Resilience

Auto-reconnect with exponential backoff

All channels automatically reconnect on disconnection with exponential backoff. No manual intervention needed for transient network issues.

Cron Scheduling

Agent mode or echo mode

Cron expressions, intervals, one-shot timers. Agent mode triggers a full LLM turn; echo mode delivers messages directly. Auto-expiry and run limits.

Credentials

Multi-backend credential management

OS keyring (macOS Keychain, GNOME Keyring, Windows Credential Manager), external credential helpers (1Password, Bitwarden, custom scripts), and 29 OXICRAB_* env var overrides. Resolution: env → helper → keyring → config.toml.

Security

Defense in depth

Per-channel DM policy (allowlist/pairing/open) with default-deny sender allowlists, bidirectional leak detection (two-phase Aho-Corasick + regex scanning for API key patterns across plaintext, base64, and hex encodings — inbound scanning redacts secrets before they reach the LLM or session history, outbound scanning redacts before sending to channels), shell AST analysis (structural command validation via brush-parser), kernel-level process sandbox (Landlock on Linux, Seatbelt on macOS), shell command allowlists + regex blocklists, SSRF protection, path traversal prevention, secret redaction in logs, constant-time webhook signature validation, config validation (minimum secret lengths, reserved header blocking, command sanitization), tool name shadowing prevention (built-in tools cannot be overridden by MCP or runtime tools), atomic cron claiming to prevent double-firing.

Voice

Dual-backend transcription

Local whisper.cpp inference or cloud Whisper API. Automatic routing with fallback. Audio converted to 16kHz mono via ffmpeg subprocess.

MCP

Model Context Protocol support

Connect external tool servers via child processes. Tools are auto-discovered at startup and registered as native tools with full middleware pipeline.

HTTP Gateway

REST API, webhooks, and A2A protocol

Programmatic access via POST /api/chat. Status dashboard at /status. Named webhook endpoints with HMAC-SHA256 signature validation. Google A2A protocol for agent discovery and interoperability. Echo mode for channel testing without LLM.

Context Providers

Dynamic system prompt injection

Shell commands that inject live context into every LLM turn. Cached with configurable TTL, dependency-checked, and silently skipped on failure. Add git status, environment info, or any external data to the system prompt.

JSON Mode

Structured output from any provider

Per-request JSON mode and JSON schema support. Native implementation for OpenAI and Gemini. System prompt hint for Anthropic. Configurable via ResponseFormat.

Token Logging

Raw LLM token usage tracking

All LLM calls log token usage (input, output, cache) to SQLite. View usage by model and date with oxicrab stats tokens. No estimated pricing — token counts are the ground truth.

Circuit Breaker

Provider resilience

Three-state circuit breaker (Closed → Open → HalfOpen) wraps the LLM provider. Trips on transient errors (429, 5xx, timeout) but ignores auth failures. Configurable threshold, recovery timeout, and probe count.

Doctor

System diagnostics

Run oxicrab doctor to check config, workspace, provider connectivity, channel status, voice backends, external tools, and MCP servers. PASS/FAIL/SKIP output for every check.

Getting Started

Up and running in minutes

Pre-built binaries are published for every release. Pick your platform and go.

Install

Download the latest release for your platform.

# Debian / Ubuntu
curl -LO https://github.com/oxicrab/oxicrab/releases/latest/download/oxicrab_VERSION_amd64.deb
sudo dpkg -i oxicrab_*_amd64.deb

# Fedora / RHEL
curl -LO https://github.com/oxicrab/oxicrab/releases/latest/download/oxicrab-VERSION.x86_64.rpm
sudo rpm -i oxicrab-*.x86_64.rpm

# macOS (Apple Silicon)
# Download the DMG from GitHub Releases, or build from source:
# cargo install --path .

ARM64 Linux and standalone tarballs also available on the Releases page.

Configure

Create config with your API keys and channel tokens.

oxicrab onboard
# or manually:
mkdir -p ~/.oxicrab
cp config.example.toml ~/.oxicrab/config.toml

Run

Start oxicrab, then talk to it from your configured channel.

oxicrab gateway
# then in Slack / Telegram / Discord / WhatsApp:
@oxicrab summarize my inbox

See CLI Reference for all commands and Workspace Docs for file layout and persistence.

Deploy as a service

Run oxicrab as a persistent daemon.

# Linux (systemd user service)
cp deploy/oxicrab.service ~/.config/systemd/user/
systemctl --user enable --now oxicrab

# macOS (launchd)
cp deploy/com.oxicrab.gateway.plist \
   ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.oxicrab.gateway.plist

See Deployment for Docker, Docker Compose, building from source, and detailed service configuration.

Architecture

Crate-based and modular

The codebase is split into focused crates: channels, routing, gateway, providers, memory, safety, and tool crates. The binary composes them into one bot.

Channel → MessageBus → Router → AgentLoop → Providers + Tools
deterministic routing → constrained/full LLM → policy-enforced tool execution → session update

`oxicrab-channels`

Telegram, Discord, Slack, WhatsApp, and Twilio adapters. Channel-specific delivery, pairing flows, formatting, and reconnect behavior live here.

`oxicrab-router`

Deterministic-first routing, strict routing policy, context state machine, semantic tool narrowing, metrics, and replay traces.

`oxicrab-gateway`

HTTP API, status page, webhooks, A2A endpoints, auth middleware, and rate limiting for non-chat entry points.

`oxicrab-providers`

Anthropic, OpenAI, Gemini, and OpenAI-compatible providers, with model routing, fallback chains, and JSON mode support.

`oxicrab-memory`

SQLite-backed memory, sessions, cron persistence, embeddings, indexing, and retrieval used across the whole system.

Tool Crates

Web, system, API, Google, browser, Obsidian, RSS, and transcription crates keep tool logic isolated instead of packing everything into one module tree.

Your AI assistant framework, built in Rust.