Vargos

Self-hosted agent OS. Give any LLM persistent memory, multi-channel presence, tools, scheduling, and sub-agent orchestration — all on your hardware.

What It Does

• Any LLM — Anthropic, OpenAI, Google, OpenRouter, Ollama, LM Studio, Groq, Together, DeepSeek, Mistral, Fireworks, Perplexity
• Multi-channel presence — connect WhatsApp and Telegram bots, route messages to the agent
• Automatic tool discovery — every service feature becomes available as an agent tool
• MCP integration — expose your agent's tools to other applications, connect external tool servers
• Persistent memory — vector + keyword search across workspace files and conversation history
• Scheduled tasks — run agent tasks on a schedule, send results to channels
• Webhooks — trigger agent tasks from external systems (GitHub, monitoring, etc.)
• Subagent delegation — agents can spawn child agents for parallel or hierarchical work
• Media intelligence — images and audio handled automatically (vision, transcription)

Quick Start

git clone https://github.com/chozzz/vargos.git
cd vargos
pnpm install
pnpm start

First run prompts for LLM provider, model, and API key. Config is saved to ~/.vargos/config.json.

Architecture

                    ┌──────────────────────────────────────┐
                    │  Gateway  (EventEmitterBus + TCP)    │
                    └────────────┬─────────────────────────┘
                                 │
         ┌───────────────────────┼────────────────────────┐
         │                       │                        │
         ↓                       ↓                        ↓
    ┌─────────┐           ┌──────────┐            ┌────────────┐
    │ Config  │           │ Agent    │            │   CLI      │
    │ Log     │           │ Channels │            │  External  │
    │ Memory  │           │ Cron     │            │  Clients   │
    └─────────┘           └──────────┘            └────────────┘

Services are isolated — no shared state, communication only through internal APIs. This makes Vargos reliable and easy to extend.

Key Concepts

• Agent — An AI system that reads instructions, sees available tools, and decides what to do to help you
• Channel — A messaging platform (WhatsApp, Telegram) where users can talk to the agent
• System prompt — Instructions that tell the agent how to behave (from files like CLAUDE.md)
• Session — A conversation thread with one user; Vargos remembers previous messages
• Tool — A capability the agent can use (read a file, run code, fetch a URL, send a message)
• Workspace — Your project folder where Vargos stores instructions, skills, and conversation history

Message Handling

Messages go through a simple pipeline: receive → process → execute → respond. The agent has access to all Vargos tools and your workspace context. See Channels for details.

Documentation

Doc	Description
Getting Started	Install, first run, config wizard
Configuration	Full config reference
Channels	WhatsApp and Telegram setup
Webhooks	Inbound HTTP triggers
MCP	MCP server and client integration
Sessions	Session types and lifecycle
Runtime	How agents execute
Workspace Files	AGENTS.md, SOUL.md, TOOLS.md reference
CLI	Commands and gateway lifecycle
Troubleshooting	Common issues and fixes
Roadmap	Planned features

Examples

• Webhook Automation — GitHub, monitoring alerts
• MCP Integration — Connect external tool servers
• Scheduled Research — Daily reports via cron
• Multi-Channel Presence — WhatsApp + Telegram + CLI

Development

pnpm install          # Install deps
pnpm start            # Start runtime
pnpm test             # Tests (watch mode)
pnpm run test:run     # Tests (single run)
pnpm run typecheck    # TypeScript check
pnpm lint             # ESLint + typecheck

Contributing

See CONTRIBUTING.md for architecture details, event reference, and development guidelines.

License

Apache-2.0