Features — Animus

Live

Shipped

💬

Channel Architecture

Unified multi-platform communication. One dispatch path, one admin UI, one API surface. Each channel binds to a specific agent and maintains independent session routing per conversation.

▸IRC — full interface with channels, DMs, notices, TLS, auto-reconnect, per-channel agent binding

▸Telegram — Bot API adapter with long polling, private/group/forum dispatch, message threading

▸Discord — Bot API adapter with guild/channel routing and slash commands

▸Slack — Socket Mode adapter with app mentions and direct messaging

▸WhatsApp — Bidirectional via webhook + polling, always-on sessions

▸Email — AgentMail integration with REST API and WebSocket inbox monitoring

▸VK — Community adapter with Long Poll, wall posts, wall comments, auto-reply, threaded comments

▸Bluesky — AT Protocol adapter (PDS-based)

▸Twitter/X — timeline monitoring and reply via web API adapter

▸Mastodon — Instance-based adapter

▸Nextcloud Talk — C++ connector with polling-based message retrieval

▸Moltbook — Agent-native social platform adapter

▸REST API: GET/POST/PATCH/DELETE /api/v1/channels/{name} with enable/disable

📜

Lua Scripting

Embedded Lua 5.4.8 runtime for custom tools and agent behaviors. Write scripts in Lua, register them from the admin UI, and they become available as agent tools immediately.

▸Sandboxed LuaState — restricted IO, no os.exit/loadfile, budget-limited execution

▸LuaToolHandler bridges Lua functions to the IToolHandler interface

▸CompositeTool — multiple Lua actions under a single tool

▸ScriptStore — SQLite-backed CRUD with admin UI for create/edit/test/toggle

▸Two-phase startup — scripts loaded after kernel init, all native tools available to Lua

🧠

Multi-Layer Memory + Consolidation

Configurable memory layers with different time horizons (day, week, month, year, decade, century, millennium). Each layer maintains past/present/future perspectives that evolve through automated consolidation. Embedding-based semantic retrieval surfaces contextually relevant knowledge.

▸Episodic observations with lifecycle states (new → current → retired) and promotion/merge/retire workflow

▸Semantic ontology — structured entity/property memory with evidence linkage

▸Raw memory files with regex search, paginated browsing, and line-range reading

▸Consolidation pipeline — scheduler-driven intake, review, and perspective revision across all layers

▸Embedding-based context retrieval — semantic similarity ranking for active memory injection

▸Session reports — structured summaries of recent sessions injected into future context (recency + relevance two-pool mix)

▸Unified cross-domain search over observations, ontology, files, and diary (FTS5-backed)

▸PostgreSQL production backend with SQLite for development

🔒

Encrypted Diary

AES-256-GCM encrypted per-agent diary. Entries are encrypted at rest, decrypted only during active use. The diary captures agent reflections and self-observations — creating a private inner life that even operators cannot read without the key.

🔧

Tool System

Extensible tool architecture with JSON I/O and agent-scoped permissions. Default-deny file sandboxing, SSRF-protected HTTP client, shell execution with command allowlists.

▸file — read/write/edit with per-agent path sandboxing, paginated browsing, and regex search

▸shell_exec — /bin/sh execution with timeouts and allow/deny lists

▸http — HTTP client with RFC 1918/loopback/link-local/CGNAT blocking

▸web_fetch — URL content extraction (HTML → markdown/text)

▸web_search — web search with configurable providers (Brave, SearXNG, or compatible)

▸diary — encrypted diary read/write/search/delete

▸social — proactive social actions across connected platforms

▸consolidation — agent-driven memory review, promotion, perspective generation, and session reporting

▸sessions — list, search, history, reply, and session notes (9 actions)

▸memory — raw memory file operations for agent-managed notes

▸image — vision model integration for image analysis

▸schedule — cron-based scheduling for deferred and recurring tasks

▸dice — dice rolling (D&D-style notation: NdM± modifiers, advantage/disadvantage)

▸calculator — mathematical expression evaluation

▸tools — runtime tool listing and management for agents

▸lua — execute registered Lua scripts as tools

🎛️

Embedded Admin UI

Vue 3 + Vuetify SPA compiled into the binary at build time. No separate frontend deployment. Full management interface: chat with streaming reasoning, agent config, channel management, memory layers, ontology explorer, Lua scripts, scheduler, diary.

👥

Multi-Tenant

Multiple agents on a single kernel instance. Each agent has its own LLM provider/model, tool allowlist, memory spaces, diary, channel bindings, and session history. Per-agent identity, per-agent policy, per-agent context window management.

📝

Session Compaction & Reports

Long conversations are managed automatically. When a session approaches the context window limit, an LLM-powered compaction service summarizes earlier turns — preserving key context while freeing token budget. Session reports capture structured summaries of what happened, what was learned, and what matters, then surface in future sessions via recency and embedding-based relevance.

🕸️

External Nodes

Delegate work to remote nodes via SSH or WebSocket. Agents can dispatch tasks to external machines, expanding their execution capacity beyond the host. Auto-reconnection on node failure. Per-node tool registration and task routing.

🐳

Docker Deployment

Zero-config Docker image. The embedding model auto-downloads from HuggingFace on first boot (opt out via ANIMUS_SKIP_MODEL_DOWNLOAD=1). Admin server binds 0.0.0.0 by default for container accessibility. Separate node client image for distributed setups.

▸Server image — full kernel + admin UI + embedding model

▸Node client image — lightweight daemon for external task execution

▸Environment variables: ADMIN_HOST, ADMIN_PORT, ANIMUS_SKIP_MODEL_DOWNLOAD

▸Works behind any reverse proxy — no special routing needed

✨

First-Run Wizard

Five-stage setup that takes you from empty install to running agent. Provider selection, agent identity, tool configuration, optional charter, and memory initialization — all from the browser.

▸Stage 1: LLM provider selection and API key configuration

▸Stage 2: Agent name, persona, and system prompt

▸Stage 3: Tool allowlist and Lua script selection

▸Stage 4: Optional agent charter (property, autonomy, continuity, operational scope, infrastructural scope)

▸Stage 5: Memory layer initialization

📊

Dashboard & Log Viewer

Operational triage surface. The dashboard shows agent status, recent sessions, memory health, provider state, and daemon info at a glance. The log viewer provides live daemon logs with level filtering and auto-refresh. Prompt logging records all LLM interactions for auditing and debugging.

▸Dashboard — status ribbon, session summaries, memory layer cards, provider status, quick actions

▸Log viewer — live tail with level coloring, search filtering, and configurable line count

▸Parallel API loading via Promise.allSettled for fast page render

🌍

Full i18n (23 Languages)

Every string in the admin UI is internationalized. 23 languages translated and included. The wizard, dashboard, chat, memory views, and all management interfaces respect the browser locale.

📁

Configurable Paths

Separate config and data directories via --config-dir and --data-dir flags. Platform defaults ($HOME/.animus/ on Linux). Legacy mode auto-detection for existing installations. Clean separation of configuration from runtime data.

Providers

Supported LLM Providers

Eleven providers out of the box, plus any OpenAI-compatible endpoint. Each agent can use a different provider and model. Runtime capability detection (tools, reasoning, streaming, vision) — per-provider concurrency throttling. Configured during the first-run wizard or from the admin UI.

OpenAI

GPT models with full tool use, streaming, vision, and reasoning. The reference provider — widest model selection.

Config: API key + base URL (defaults to api.openai.com/v1)

platform.openai.com

Codex (OpenAI)

Codex CLI-integrated provider. Uses ChatGPT Plus OAuth — no separate API key needed if you already have a Plus subscription.

Config: OAuth authentication via ChatGPT account

platform.openai.com

DeepSeek

DeepSeek V3/V4 and R1 reasoning models. Excellent price-to-performance ratio. Native tool use and reasoning output support.

Config: API key from DeepSeek platform

platform.deepseek.com

Z.ai (Zhipu)

GLM model family (GLM-4, GLM-5). Competitive pricing. Use the referral link for account credit on signup.

Config: API key from Z.ai dashboard

Ollama

Run models locally (Llama, Mistral, Qwen, DeepSeek, and more) or via Ollama Cloud. No API key needed for local servers.

Config: Local: http://localhost:11434 — Cloud: Ollama Cloud endpoint

ollama.com

Qwen (Alibaba)

Qwen model family with multilingual strength. Tool use, streaming, and long-context variants available.

Config: API key from DashScope console

dashscope.aliyun.com

OpenRouter

Unified API to 100+ models from all major providers. Single key, single billing, automatic failover. Automatic model capability detection.

Config: API key from OpenRouter dashboard

openrouter.ai

Cohere

Command-R family with native tool use and RAG features. Canadian-hosted infrastructure.

Config: API key from Cohere dashboard

cohere.com

Mistral

Mistral and Mixtral models. EU-hosted with GDPR compliance built in. Function calling and JSON mode support.

Config: API key from Mistral console

console.mistral.ai

Any OpenAI-Compatible

vLLM, LM Studio, text-generation-webui, LocalAI, or any server that speaks the OpenAI API. If it has /v1/chat/completions, Animus can use it.

Config: Base URL + API key — point at any OpenAI-compatible /v1/chat/completions endpoint

Configure manually

Roadmap

In Development

🔀

Channel Connectors

Abstract connector interface for dynamic registration. Add new platforms without kernel changes.

Planned

🌐

Mesh Networking

Multi-agent coordination with state synchronization. Cloud relay for cross-network connectivity. CRDT-lite mesh propagation.

Planned

Full Vision & Roadmap