conduit

Conduit Go Gateway

A rewrite of the Conduit gateway core in Go (single static binary, pure-Go SQLite), with native channel adapters, vector database integration, and a pluggable tool/skill architecture.

Architecture

                  ┌────────────┐  ┌────────────┐  ┌────────────┐
                  │  Telegram  │  │  TUI Chat  │  │ SSH (Wish) │
                  │   Client   │  │   Client   │  │   Client   │
                  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘
                        │               │               │
┌───────────────────────┼───────────────┼───────────────┼───────┐
│                         Conduit Go Gateway                    │
│                       │               │               │       │
│  ┌────────────────────┴───────────────┴───────────────┴────┐  │
│  │              Channel Manager / WebSocket API            │  │
│  │           Unified adapter lifecycle management          │  │
│  └─────────────────────────────────────────────────────────┘  │
│                               │                               │
│               ┌───────────────┴───────────────┐               │
│               ▼                               ▼               │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │                   Native Go Adapters                    │  │
│  │                                                         │  │
│  │  • Telegram (go-telegram/bot)                           │  │
│  │  • Discord (planned)    • Slack (planned)               │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  Core Services                                          │  │
│  │  • Session Store (SQLite)   • AI Router (Anthropic/OAI) │  │
│  │  • Tool Registry            • WebSocket API             │  │
│  │  • Config Management        • HTTP Endpoints            │  │
│  │  • Authentication System    • Web Search Integration    │  │
│  │  • Heartbeat Monitoring     • Alert Processing          │  │
│  │  • SSH Server (Wish)        • TUI (BubbleTea)           │  │
│  │  • MQTT Event Ingest        • Kubernetes (client-go)    │  │
│  └─────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────┘

Quick Start

# Build
make build

# Create auth token
./bin/conduit token create --client-name "my-client" --role owner

# Start server
./bin/conduit server

# Launch terminal UI. The first run needs the token; read it into a variable
# so it stays out of shell history. It is saved to ~/.conduit/tui.json (0600)
# and reused, so later runs are just `./bin/conduit tui`.
read -rsp 'Token: ' CONDUIT_TOKEN; echo
./bin/conduit tui --token "$CONDUIT_TOKEN"

See Getting Started for detailed setup instructions.

Features

Core Infrastructure

• Gateway Architecture — Channel manager with unified lifecycle management
• Session Management — SQLite-based persistent session storage
• AI Provider Routing — Anthropic and OpenAI with automatic fallback
• Context Compaction — Automatic summarization of long sessions to free context space
• Tool Registry — 34 built-in tools (24 core + 10 optional) with sandbox execution
• Tool SelfTest — All built-in tools expose a SelfTest capability, allowing the gateway to programmatically verify tool health at startup or on demand

Access Methods

• Terminal UI (TUI) — Full-featured chat client with streaming responses
• SSH Access — Remote TUI access via Wish library
• Telegram Bot — Native Go adapter with full Bot API support
• WebSocket API — Real-time bidirectional communication

Search & Memory

• Brain (Cognitive Memory) — Tiered memory system: long-term (SQLite), working (in-process, per user), and scratchpad (LIFO stack). Salience-scored with configurable weights, auto-promotion, and sub-agent working memory sharing. Eliminates context window poisoning — instead of dumping entire files into the prompt to retrieve a single fact, Brain returns just the fact (30 bytes vs. 12KB+). This dramatically reduces token waste, lowers cost, and keeps the context window clear for actual reasoning — especially critical for smaller models (Haiku, local quantized) where every token counts
• REM Sleep Cycle — A 5-phase memory consolidation process inspired by biological sleep. Phases: Triage (identify valuable working memory), Consolidation (promote high-value entries to LTM), Pruning (evict stale/low-value entries), Integration (cross-reference with workspace files), and Grooming (staleness tracking across all sources). Runs on a configurable schedule to keep long-term memory lean and relevant
• SPAR Reflect — Cross-session learning loop. Tool outcomes are captured automatically on every execution, session summaries are written on idle/farewell/context budget, and the nightly REM Reflect phase clusters patterns (e.g., "WebFetch fails frequently") and feeds them back into the agent's Situation Awareness prompt section
• FTS5 Full-Text Search — SQLite-based document, message, and brain LTM search
• Vecgo (Semantic Search) — Hybrid vector+keyword search via MemorySearch. Batteries-included: auto-detects Ollama at localhost and enables semantic embeddings with zero config. Searches like "power setup" find "solar inverter" even without exact keyword match. Supports Ollama (local) and OpenAI embedders. Results merged with FTS5 via Reciprocal Rank Fusion
• Web Search — Brave Search API via the WebSearch tool

Communication & Vision

• Telegram Photo Vision — Send photos to the Telegram bot for LLM image analysis (JPEG, PNG, GIF, WebP up to 20MB)
• Google Workspace — Gmail search/send and Calendar management via gws CLI
• Text-to-Speech — TTS synthesis for voice responses
• Remote SSH — Multi-host SSH execution with security tiers, persistent sessions, tunnels, and SCP

Automation

• Chain Workflows — Multi-tool sequences with dependencies and variables
• Cron Scheduling — Recurring task execution
• Agent Heartbeat — Automated HEARTBEAT.md task processing with quiet-hours deferral and audited, circuit-broken alert delivery
• Skills System — Extensible AI capabilities via SKILL.md files

IoT & Home Automation

• MQTT Integration — Subscribe to MQTT topics (zigbee2mqtt, Home Assistant) for real-time device data
• Event Buffering — In-memory per-topic ring buffers with age-based pruning
• Heartbeat Monitoring — Natural language rules in HEARTBEAT.md to check sensors and alert on anomalies

SRE & Infrastructure

• Kubernetes Tool — Native client-go integration with multi-cluster support, security tiers, pod exec, port forwarding, resource watch
• PagerDuty — REST API v2 tool for incident management, services, and on-call queries
• Datadog — Metrics, logs, and monitors tool with separate monitor management
• SRE Incident Correlation — Cross-references PagerDuty incidents with Datadog metrics for root-cause analysis

Providers

Conduit supports multiple AI providers. Configure them in the ai.providers array in your config JSON.

Anthropic (default)

{
  "name": "anthropic",
  "type": "anthropic",
  "model": "claude-sonnet-4-6",
  "auth": {
    "type": "oauth",
    "oauth_token": "${ANTHROPIC_OAUTH_TOKEN}"
  }
}

Or with an API key:

{
  "name": "anthropic",
  "type": "anthropic",
  "model": "claude-sonnet-4-6",
  "auth": {
    "type": "api_key",
    "oauth_token": "${ANTHROPIC_API_KEY}"
  }
}

Ollama

{
  "name": "ollama",
  "type": "ollama",
  "base_url": "http://localhost:11434/v1",
  "model": "llama3.1"
}

Important: The base_url must include /v1. Ollama's OpenAI-compatible endpoint is at /v1/chat/completions, and Conduit appends /chat/completions to the base URL automatically.

No authentication is needed for local Ollama instances.

OpenAI-compatible

Any OpenAI-compatible API can be used with type: "openai":

{
  "name": "my-provider",
  "type": "openai",
  "base_url": "https://api.example.com/v1",
  "api_key": "${MY_API_KEY}",
  "model": "my-model"
}

Switching providers at runtime

Use /provider to list available providers and /provider <name> to switch. The model automatically updates to the new provider's default when switching.

Model aliases

Map short names to full model IDs across providers:

"model_aliases": {
  "haiku": "claude-haiku-4-5-20251001",
  "sonnet": "claude-sonnet-4-6",
  "opus": "claude-opus-4-6",
  "default": "claude-haiku-4-5-20251001"
}

Use /model <alias> to switch models. The provider auto-resolves based on the model name.

Documentation

Guides

• Environment & Secrets — Environment configuration
• OAuth Setup — OAuth device flow setup
• Telegram Adapter — Telegram bot configuration

Development

• Tool Execution Integration — Tool execution system details

Project Structure

conduit/
├── cmd/gateway/           # CLI entry point and commands
├── internal/
│   ├── gateway/           # Core gateway orchestration
│   ├── ai/                # AI provider routing
│   ├── tools/             # Tool registry and implementations
│   │   ├── k8s/           # Kubernetes tool (client-go)
│   │   ├── ssh/           # SSH remote execution tool
│   │   └── mqtt/          # MQTT tool
│   ├── channels/          # Channel adapters (Telegram, TUI)
│   ├── mqtt/              # MQTT event ingest (zigbee2mqtt, HA)
│   ├── sessions/          # SQLite session storage
│   ├── tui/               # BubbleTea terminal UI
│   ├── ssh/               # Wish SSH server
│   ├── auth/              # Token authentication
│   ├── config/            # Configuration management
│   └── ...
├── vecgo/                 # Vector database library (standalone)
├── reference/             # Documentation
├── configs/               # Example configurations
└── Makefile

Development

make build          # Build binary
make test           # Run tests
make lint           # Run linters
make dev            # Auto-restart on changes (requires 'air')
make health         # Check if running

Run specific tests:

go test -v -run TestFunctionName ./internal/package/...
go test -v ./internal/tools/...

Task Management

Uses beads-rust (br command) for task tracking:

br ready                    # Show actionable tasks
br create "task title"      # Create task
br close br-abc123          # Complete task
br sync --flush-only        # Export to git

License

MIT License - see LICENSE for details.