Quick Start • Architecture • Features • Deployment • Documentation

---

Operational Status

Capability	Status	Notes
Core runtime	✅ Operational	Event-driven execution, worker pool
Gateway	✅ Operational	HTTP endpoints, health checks, SSE streaming
Event streaming	✅ Operational	OutboundEvent system
Remote worker	✅ Operational	Authenticated remote execution
Tool sandbox	✅ Operational	Policy → validation → sandbox runner → audit
CLI/TUI	✅ Operational	Command-line interface
Telegram	✅ Operational	Channel integration
Discord	✅ Operational	Channel adapter with tests
Slack	✅ Operational	Channel adapter with tests
Hive	⚠️ Feature-gated	Multi-agent swarm (experimental, build with --features hive)
Browser	✅ Operational	Browser automation enabled

Build Status:

• ✅ cargo check passes (default features)
• ✅ cargo test passes (1500+ tests)
• ✅ Rust 1.88.0 toolchain

Feature Flags:

• Default: telegram, mcp, tui
• Experimental (not in default): hive, skills, automation, filestore, codex-oauth
• Build with experimental: cargo build --features "hive,skills,automation,filestore"

What is Electris

Electris is an AI agent runtime written in Rust, designed for deploying autonomous agents across multiple messaging channels. It uses a modular microkernel architecture with event-driven execution.

// The core philosophy: reliability at scale
pub async fn deploy() -> Result<Eternity, Never> {
    Agent::new()
        .channels([Telegram, Discord, Slack, CLI])
        .providers([Anthropic, OpenAI, Gemini, Grok, OpenRouter])
        .tools([Shell, Browser, Git, Files, Web, MCP])
        .memory(λ_Memory)
        .swarm(Many_Tems)
        .run_forever()
        .await
}

Why Electris?

Metric	Value
Binary Size	~15 MB (stripped release)
Memory Footprint	< 50 MB baseline
Cold Start	< 100ms
Test Coverage	1522 tests
Clippy Warnings	Core clean, experimental has warnings
Channels	4 (Telegram, Discord, Slack, CLI)
AI Providers	6 (Anthropic, OpenAI, Gemini, Grok, OpenRouter, Codex OAuth)
Built-in Tools	10+ categories

Quick Start

Prerequisites

• Rust 1.88+ (rustup update stable)
• Chrome/Chromium (for browser automation tool)
• SQLite or PostgreSQL (for memory persistence)

Installation

# Clone the repository
git clone https://github.com/electro-labs/Electro.git
cd Electro

# Build optimized release binary
cargo build --release

# Verify installation
./target/release/electro --version

Three Modes of Operation

1. Interactive TUI (Fastest way to experiment)

./target/release/electro tui

Features:

• Inline code editing with syntax highlighting
• File tree navigation
• Real-time streaming responses
• Session history persistence

2. Server Mode with Telegram Bot

# Set your bot token
export TELEGRAM_BOT_TOKEN="your-token-here"

# Start the server
./target/release/electro start

3. Docker Deployment (Production)

# Copy and edit configuration
cp .env.example .env
# Edit .env with your tokens and settings

# Launch with docker-compose
docker-compose up -d

Architecture

Electris follows a modular microkernel architecture with 22 purpose-built crates:

┌─────────────────────────────────────────────────────────────────┐
│                        Electris Binary                          │
├─────────────────────────────────────────────────────────────────┤
│  electro-gateway   │  HTTP server, WebSocket, health, metrics  │
│  electro-channels  │  Telegram • Discord • Slack • CLI • TUI     │
│  electro-agent     │  Agent runtime, reasoning, execution      │
│  electro-hive      │  Swarm intelligence, Many Tems            │
├─────────────────────────────────────────────────────────────────┤
│  electro-providers │  Anthropic • OpenAI • Gemini • Grok       │
│  electro-codex-oauth│ ChatGPT Plus/Pro via OAuth PKCE          │
│  electro-mcp       │  Model Context Protocol client/server       │
├─────────────────────────────────────────────────────────────────┤
│  electro-tools     │  Shell • Browser • Git • Files • Web       │
│  electro-memory    │  SQLite • PostgreSQL • λ-Memory           │
│  electro-vault     │  ChaCha20-Poly1305 encryption             │
│  electro-observable│  OpenTelemetry tracing & metrics          │
└─────────────────────────────────────────────────────────────────┘
          │
    ┌─────┴─────┐
    │ electro-core│  Traits, types, errors, config
    └───────────┘

Key Architectural Decisions

1. Zero-Copy Message Flow: Messages pass through channels without serialization overhead
2. Per-Chat Worker Pools: Each conversation gets isolated worker slots with cancellation tokens
3. Tiered Model Routing: Automatically switches between fast/cheap and slow/powerful models
4. Circuit Breakers: Automatic failover when AI providers experience degradation
5. Graceful Degradation: Core functionality survives partial system failures

---

Features

Phase 0 — Reliability Foundation

Feature	Module	Description
Graceful Shutdown	src/main.rs	SIGTERM handling with 30s drain + checkpointing
Circuit Breaker	electro-agent/src/circuit_breaker.rs	Automatic failover with exponential backoff
Reconnection	electro-channels/src/	Exponential backoff for all channel connections
Streaming	electro-agent/src/streaming.rs	Real-time response streaming with throttling

Phase 1 — Agent Intelligence

Feature	Module	Description
Verification Engine	electro-agent/src/runtime.rs	Self-checking for hallucinations
Task Decomposition	electro-agent/src/task_decomposition.rs	Breaks complex tasks into subtasks
Persistent Queue	electro-agent/src/task_queue.rs	Checkpoint-resume for long tasks
Context Management	electro-agent/src/context.rs	Surgical token budgeting
Self-Correction	electro-agent/src/self_correction.rs	Automatic error recovery
Cross-Task Learning	electro-agent/src/learning.rs	Improves from past interactions

Phase 2 — Self-Healing

Feature	Module	Description
Watchdog	electro-agent/src/watchdog.rs	Monitors agent health
State Recovery	electro-agent/src/recovery.rs	Resume from crashes
Health Heartbeat	electro-automation/src/heartbeat.rs	Liveness probes
Memory Failover	electro-memory/src/lib.rs	Backend redundancy

Phase 3 — Efficiency

Feature	Module	Description
Output Compression	electro-agent/src/output_compression.rs	Reduces token usage
Prompt Optimization	electro-agent/src/prompt_optimizer.rs	Self-tuning system prompts
Model Routing	electro-agent/src/model_router.rs	Cost/performance optimization
History Pruning	electro-agent/src/history_pruning.rs	Semantic importance-based trimming

Phase 4 — Multi-Channel

Feature	Status	Description
Telegram Bot	✅	Full webhook + long-poll support
Discord Bot	✅	Slash commands + DMs
Slack App	✅	Socket Mode + Block Kit
CLI	✅	Interactive shell mode
TUI	✅	Terminal UI with file explorer

Phase 5 — Cloud Scale

Feature	Module	Description
S3/R2 FileStore	electro-filestore/src/s3.rs	Object storage backend
OpenTelemetry	electro-observable/src/	Distributed tracing
Multi-Tenancy	electro-core/src/tenant_impl.rs	Workspace isolation
OAuth Flows	electro-gateway/src/identity.rs	Identity management
Horizontal Scaling	electro-core/src/orchestrator_impl.rs	Worker node orchestration

Phase 6 — Advanced Capabilities

Feature	Module	Description
Parallel Tools	electro-agent/src/executor.rs	Concurrent tool execution
Agent Delegation	electro-agent/src/delegation.rs	Agent-to-agent task handoff
Proactive Tasks	electro-agent/src/proactive.rs	Scheduled/conditional execution
Adaptive Prompts	electro-agent/src/prompt_patches.rs	Runtime prompt evolution
Vision Support	electro-agent/src/runtime.rs	Image understanding

---

Deployment

Environment Configuration

Create .env from .env.example:

# Required: At least one AI provider
ANTHROPIC_API_KEY="sk-ant-..."
OPENAI_API_KEY="sk-..."
GOOGLE_API_KEY="..."

# Required: At least one channel
TELEGRAM_BOT_TOKEN="..."
# or
DISCORD_BOT_TOKEN="..."
# or
SLACK_BOT_TOKEN="..."

# Optional: Enhanced features
ELECTRO_MEMORY_BACKEND="sqlite"  # or "postgres"
ELECTRO_VAULT_KEY="$(openssl rand -hex 32)"
ELECTRO_OAUTH_ENCRYPTION_KEY="..."

Docker Compose (Full Stack)

version: '3.8'
services:
  electro:
    build: .
    ports:
      - "3000:3000"
    environment:
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./data:/data
    depends_on:
      - postgres
  
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: electro
      POSTGRES_USER: electro
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data

Kubernetes (Helm Chart)

helm repo add electro https://electro-labs.github.io/charts
helm install my-agent electro/electro \
  --set telegram.token="$TELEGRAM_BOT_TOKEN" \
  --set anthropic.apiKey="$ANTHROPIC_API_KEY"

---

Development

Workspace Structure

Electro/
├── src/                    # Main binary & CLI
│   ├── main.rs            # Entry point
│   ├── app/               # Server implementation
│   └── bin/               # Additional binaries
├── crates/                # 22 workspace crates
│   ├── electro-core/      # Core traits & types
│   ├── electro-agent/     # Agent runtime
│   ├── electro-gateway/   # HTTP/WebSocket server
│   ├── electro-runtime/   # Async runtime & config
│   ├── electro-providers/ # AI provider implementations
│   ├── electro-channels/  # Messaging channels
│   ├── electro-memory/    # Persistence layer
│   ├── electro-tools/     # Tool implementations
│   ├── electro-vault/     # Secret encryption
│   ├── electro-hive/      # Swarm intelligence
│   ├── electro-mcp/       # MCP protocol
│   └── ...
├── docs/                   # Documentation
├── docker/                 # Container configs
└── scripts/               # Build & deploy scripts

Common Commands

# Development loop
cargo check --workspace                    # Fast compile check
cargo test --workspace --lib              # Run unit tests
cargo test --workspace --test integration # Run integration tests
cargo clippy --workspace --all-targets --all-features -- -D warnings

# Release builds
cargo build --release --bin electro        # Main binary
cargo build --release --bin worker-node    # Worker node

# Features
cargo build --features discord,postgres    # With Discord + PostgreSQL
cargo build --no-default-features --features cli  # Minimal CLI-only

Testing

# Run all tests
cargo test --workspace

# Run with specific features
cargo test --workspace --features browser,mcp

# Generate coverage
cargo tarpaulin --workspace --out Html

---

Security

Electris implements defense-in-depth security:

• Encryption: ChaCha20-Poly1305 for secrets at rest
• Sandboxing: Tool execution in configurable sandboxes
• Tenant Isolation: Workspace-level data separation
• OAuth PKCE: Secure authentication flows
• Input Validation: Strict schema validation on all inputs
• Audit Logging: Complete operation trails

See SECURITY.md for detailed security posture.

---

Performance Benchmarks

Scenario	Latency	Memory	Throughput
Cold start	85ms	42 MB	-
Single chat	-	48 MB	12 msg/sec
100 concurrent chats	-	156 MB	340 msg/sec
Tool execution (shell)	45ms	+2 MB	-
Browser screenshot	1.2s	+15 MB	-

Benchmarked on AMD Ryzen 9 5950X, 64GB RAM, NVMe SSD

---

Roadmap

Q1 2025

• Vision model support
• Discord/Slack channels
• Parallel tool execution

Q2 2025

• Web dashboard v2
• Custom tool registry
• Fine-tuning pipeline

Q3 2025

• WASM plugin system
• GraphRAG integration
• Voice channel support

---

Community

• Discord — Real-time chat & support
• GitHub Discussions — Long-form discussion
• Issues — Bug reports & feature requests

---

License

MIT License — See LICENSE for details.

---

_{Built with ⚡ by the Electro Labs team and contributors.}