Helios

Your AI that sheds light - A security-first, modular AI assistant framework built on the Claude Agent SDK.

Features

• Multi-Provider Support: Anthropic Claude (default), OpenRouter, OpenAI, Ollama
• Telegram Integration: Chat with your AI assistant via Telegram
• Tool Execution: Bash, file operations, SSH, Docker management
• Scheduled Tasks: Cron-based task scheduling with retry logic
• Security First: Localhost-only, no web UI, configurable sandboxing
• Persistent Sessions: SQLite-backed conversation memory

Quick Start

One-Liner Install

curl -fsSL https://helios.dev/install.sh | sh

Manual Installation

# Clone the repository
git clone https://github.com/marcusgoll/helios
cd helios

# Install dependencies
pnpm install

# Build
pnpm build

# Run setup wizard
pnpm start init

Docker

docker run -d \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e TELEGRAM_BOT_TOKEN=123456:ABC... \
  -v helios-data:/app/data \
  --name helios \
  ghcr.io/marcusgoll/helios:latest

Configuration

Configuration is stored in ~/.config/helios/config.yaml. Run helios init for interactive setup or edit manually:

providers:
  default: anthropic  # or: openrouter, openai, ollama
  anthropic:
    enabled: true
    model: claude-sonnet-4-20250514
  openrouter:
    enabled: true
    model: anthropic/claude-sonnet-4  # or any OpenRouter model

channels:
  - type: telegram
    enabled: true
    allowedUsers: []  # Empty = allow all

gateway:
  host: "127.0.0.1"
  port: 18789

Environment Variables

# Required (one AI provider)
ANTHROPIC_API_KEY=sk-ant-api03-...
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

# Optional providers
OPENROUTER_API_KEY=sk-or-v1-...      # OpenRouter (access 100+ models)
OPENAI_API_KEY=sk-...                 # OpenAI GPT models
OLLAMA_HOST=http://localhost:11434    # Local Ollama

# Provider selection (env-based)
HELIOS_PROVIDER=openrouter            # anthropic, openrouter, openai, ollama
HELIOS_MODEL=anthropic/claude-sonnet-4  # Model to use
SSH_HOST=100.93.148.25
SSH_USER=marcusgoll
ALLOWED_USERS=123456789,987654321

CLI Commands

helios init              # Interactive setup wizard
helios start             # Start the gateway
helios stop              # Stop the gateway
helios status            # Show status
helios config            # Edit configuration
helios provider list     # List AI providers
helios provider add      # Add a provider

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     HELIOS GATEWAY                          │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐   │
│  │ Hook System │ │ Session Mgr │ │ Tool Orchestrator   │   │
│  └─────────────┘ └─────────────┘ └─────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│              CHANNEL ADAPTERS (Telegram, etc.)              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│               AI PROVIDERS (Claude, GPT, etc.)              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                      TOOL LAYER                             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │  Bash   │ │  Read   │ │  Edit   │ │   SSH   │ ...      │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
└─────────────────────────────────────────────────────────────┘

Security

• Localhost Only: Gateway binds to 127.0.0.1 by default
• No Web UI: Reduces attack surface
• Tool Allowlist/Denylist: Control which commands can run
• User Restrictions: Limit which Telegram users can interact
• Audit Logging: Track all tool executions

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run in development mode
pnpm dev

# Type checking
pnpm typecheck

# Run tests
pnpm test

Project Structure

helios/
├── packages/
│   ├── core/              # Gateway, providers, tools
│   ├── channel-telegram/  # Telegram adapter
│   └── cli/               # Command-line interface
├── config/
│   └── default.yaml       # Default configuration
├── docker/
│   ├── Dockerfile
│   └── docker-compose.yml
└── scripts/
    └── install.sh         # One-liner installer

License

MIT