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
# npx (no install)
npx @chozzz/vargos
# or clone + run
git clone https://github.com/chozzz/vargos.git
cd vargos
pnpm install
pnpm startFirst run launches an interactive setup wizard (provider, model, API key). Config is saved to ~/.vargos/.
After setup: vargos start boots the server, vargos onboard re-runs the wizard, vargos config shows current settings.
Architecture
One bus owns one registry of methods. The CLI, the agent's tools, and the JSON-RPC server are all projections of that registry — register a method once, it appears everywhere.
CLI Agent tools JSON-RPC :9000
\ | /
└────────── Bus (registry) ───────┘
│
config · log · web · memory · media · agent · channel · cron · mcp
(services/<name>/ — discovered from disk, loaded by the bus)Services are isolated — no shared state, no cross-imports; they talk only via bus.call /
bus.emit. See Architecture.
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 (merged from
AGENTS.md,SOUL.md,TOOLS.mdin your workspace + per-channel persona files) - 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 Usage for details.
Documentation
| Doc | Description |
|---|---|
| Getting Started | Install, first run, config wizard |
| Configuration | Full config reference |
| Architecture | Bus registry, service contract, surfaces, hot reload |
| Usage | Channels, sessions, MCP, runtime, personas, workspace files |
| Extending | Add tools, skills, providers |
| Examples | MCP integration, scheduled research, multi-channel |
| Debugging | Debug modes and logging |
| Roadmap | Planned features |
Usage
vargos # First-run wizard or help
vargos start # Boot the daemon (bus + all services + JSON-RPC :9000)
vargos <service> # List a service's methods (e.g. vargos channel)
vargos <service> --help # Methods, descriptions, arg shapes
vargos <service> <method> … # Invoke a method (e.g. vargos channel send <to> "<msg>")
vargos onboard # Re-run setup wizardDevelopment
pnpm install # Install deps
pnpm start # Boot the daemon (alias: vargos start)
pnpm chat # Pi SDK interactive REPL bound to ~/.vargos/agent
pnpm cli # Run the CLI entrypoint directly (tsx cli.ts)
pnpm verify # Run the core acceptance checks (scripts/verify-core.ts)
pnpm run test:run # Tests (single run)
pnpm run typecheck # TypeScript check
pnpm lint # ESLint + typecheck
pnpm build # Clean + compile + copy templates → dist/Contributing
See CONTRIBUTING.md for architecture and development guidelines.