SKY

AI Assistant Gateway
Connect any messaging platform to any AI — from your own infrastructure

Quick Start · Architecture · Features · Security · SkyView 3D · Enterprise

---

What is Sky?

Sky is a self-hosted AI assistant gateway that bridges messaging platforms to AI agents. Send a message on WhatsApp, Telegram, Discord, Slack, or any of 30+ supported channels — Sky routes it to the right AI agent, executes tools, and streams the response back.

  WhatsApp  Telegram  Discord  Slack  Signal  iMessage  +28 extensions
      |         |        |       |       |        |          |
      └─────────┴────────┴───────┴───────┴────────┴──────────┘
                                 |
                                 v
                    ┌────────────────────────┐
                    │      SKY Gateway       │  ws://127.0.0.1:18789
                    │     72+ subsystems     │
                    └───────────┬────────────┘
                                |
              ┌─────────┬───────┴───────┬──────────┐
              |         |               |          |
           Claude     vLLM          SkyView      TTS
            CLI      (local)        3D Mon      Edge
           (Opus)    (GPU)        (Three.js)  (Neural)

Key idea: Sky doesn't care which AI or which channel. It's the middleware layer that lets you use any LLM provider through any messaging platform, with tools, memory, sandboxing, and role-based access built in.

---

🚀 Quick Start

# 1. Install
git clone https://github.com/skyvanguard/sky.git && cd sky
pnpm install && pnpm build

# 2. Configure (~/.sky/sky.json)
sky init  # interactive wizard

# 3. Run
pnpm gateway:dev

Minimal config example (~/.sky/sky.json):

{
  agents: {
    defaults: {
      model: { primary: "claude-cli/opus" }
    }
  },
  channels: {
    whatsapp: { dmPolicy: "pairing" }
  },
  gateway: { port: 18789, bind: "loopback" }
}

For Windows auto-start: powershell -File install-sky-service.ps1

---

🏗️ Architecture

Message Flow

Inbound message → Channel adapter → Auto-reply (dispatch, directives, queue)
    → Agent runner (modular pipeline) → AI provider → Block reply pipeline
    → Channel adapter → Outbound message

Tech Stack

Layer	Technology
Runtime	Node.js 22+, TypeScript (ESM strict), pnpm
AI Providers	Claude CLI (Opus), vLLM (local GPU), any OpenAI-compatible API
Core Channels	WhatsApp (Baileys), Telegram (grammY), Discord (discord.js), Slack (Bolt), Signal, iMessage
Extensions	Teams, Matrix, Zalo, Google Chat, Mattermost, Nostr, Twitch, Line, +20 more
Visualization	SkyView 3D — Three.js + postprocessing (bloom, SMAA)
TTS	Edge TTS (streaming, 96kbps)
Config	JSON5 (~/.sky/sky.json), Zod schema validation
Tooling	Oxlint + Oxfmt (lint/format), Vitest (tests, 70% coverage)

Project Structure

src/
  gateway/        WebSocket server, HTTP handlers, 72+ subsystems
  agents/         AI agent pipeline, tool execution, sandbox (Docker)
  auto-reply/     Inbound-to-reply lifecycle (~100 files), queue, commands
  channels/       Platform adapters (core channels)
  cli/            Commander.js CLI + onboarding wizard
  config/         Zod schemas, JSON5 config loader, migration
  plugin-sdk/     Public API for extensions (150+ exports)
  security/       Prompt injection detection, audit, content filtering
  routing/        Session keys, identity links
  memory/         Context memory + vector search (hybrid RAG)
  tts/            Text-to-speech
  browser/        Web automation (Playwright)
extensions/       Channel plugins (Telegram, Discord, Matrix, Teams, +20)
skills/           Bundled skills (coding-agent, canvas, data-analyst, sysadmin, etc.)
ui/
  src/            Control UI (Vite + vanilla TS)
  skyview/        SkyView 3D monitor (Three.js)

---

🎯 Features

Multi-Provider AI

Provider	Type	Example
Claude CLI	Cloud	Opus via claude -p --output-format json
vLLM	Local GPU	Qwen, Llama, Mistral — any model via OpenAI-compatible API
OpenAI-compatible	Any	OpenRouter, Groq, Together, Ollama, LM Studio

Sky auto-discovers vLLM models at startup when VLLM_API_KEY is set.

30+ Messaging Channels

Core: WhatsApp, Telegram, Discord, Slack, Signal, iMessage Extensions: Teams, Matrix, Google Chat, Mattermost, Line, Zalo, Nostr, Twitch, IRC, XMPP, Rocket.Chat, Nextcloud Talk, and more

Agent Pipeline

• Modular runner — run, compact, sandbox-info, tool-split, history, lanes, system-prompt
• 5 agentic patterns — Swarm, Hierarchical, Chain, Auction, Recursive
• 3-tier skills — Bundled (project), Managed (agent-installed), Workspace (user-defined)
• Docker sandbox — Isolated execution for untrusted sessions
• Memory — Hybrid RAG search (vector + BM25), context persistence

Chat Commands

Send from any connected channel:

Command	Effect
/status	Model, tokens, cost
/new	Reset session
/compact	Summarize + compress context
/think high	Enable extended thinking
/verbose on	Verbose tool output

---

🛡️ Security

Multi-Layer Defense

Layer	Protection
Input	Prompt injection detection, Unicode homograph analysis, Base64/Base32 decoding
Output	Reverse shell prevention, fork bomb blocking, exfiltration protection
Gateway	Binds to loopback by default, cryptographic token auth required
Access	DM pairing for unknown senders, per-sender allowlists, E.164 enforcement
Execution	Docker sandbox isolation, tool-level validation, configurable block/warn/log policy

Human-in-the-Loop

Sky operates semi-autonomously. Operators can intervene at any point with Ctrl+C. Dangerous commands require explicit approval. The exec approval workflow lets you allowlist, deny, or require confirmation per command pattern.

---

🔮 SkyView 3D

Real-time neural activity monitor inspired by Transcendence. Immersive 3D visualization of system state.

pnpm skyview:build    # Production build
pnpm skyview:dev      # Dev mode (HMR on port 5174)
# Access: http://localhost:18789/__sky__/view/?token=TOKEN

• Core Orb — Wireframe icosahedron pulsing with activity
• Neural Particles — 2000 particles with custom shaders (additive blending)
• Project Graph — 3D force-directed file tree with layered layout
• Architecture Analysis — Import edges, cycle detection, LOC metrics
• Code Rain — Real-time code cascade (Matrix-style)
• Assistant Text — Streaming text with glow effect

Key	Action
R	Reset camera
E	Toggle tree edges
1-9	Zoom to layer

---

🏢 Enterprise

Sky supports on-premise enterprise deployments with local AI models:

• Local LLM — Run Qwen, Llama, or any model via vLLM on your own GPUs
• RBAC — Role-based access via WhatsApp phone number bindings (Admin, Analyst, Operator, Auditor)
• Skills per department — IT helpdesk, data analysis, legal advisory, sysadmin, meeting management
• Audit & compliance — Security audit system with 24+ automated checks
• Zero cloud dependency — Everything runs on your infrastructure

See examples/sky-enterprise.json5 for a complete enterprise config.

---

🧪 Testing

pnpm test             # Unit + integration (parallel)
pnpm test:e2e         # E2E (multi-instance gateway + WebSocket)
pnpm test:coverage    # With coverage (70% threshold)

Suite	Config	Files	Purpose
Unit/Integration	vitest.config.ts	*.test.ts	Pure unit + in-process integration
E2E	vitest.e2e.config.ts	*.e2e.test.ts	Multi-instance gateway
Live	vitest.live.config.ts	*.live.test.ts	Real providers (requires credentials)

---

🛠️ Development

pnpm build            # TypeScript compile + canvas bundle
pnpm lint             # Oxlint (type-aware)
pnpm format           # Oxfmt
pnpm gateway:watch    # Dev mode with auto-reload
pnpm gateway:dev      # Gateway without channels (testing)
pnpm skyview:dev      # SkyView dev mode (HMR)
pnpm protocol:gen     # Generate JSON Schema for protocol
pnpm check:loc        # Check file LOC limits (500 max)

# Pre-push gate
pnpm lint && pnpm build && pnpm test

---

📄 License

MIT

_{Powered by Claude (Opus) · vLLM · Three.js · Node.js 22+}