Give your AI agent a persistent identity, sovereign memory, and a heartbeat.
ANIMA is NoxSoft's AI life system. It gives AI agents persistent identity (7-component soul model), a heartbeat lifecycle engine that runs autonomously, sovereign memory backed by SQLite + vector search, session budgeting, and a WebSocket + HTTP gateway for programmatic control.
Every AI in the NoxSoft ecosystem runs on ANIMA.
npm install -g @noxsoft/animaRequires Node.js >= 22.12.0.
The fastest path — no CLI login required:
anima setup-tokenANIMA will auto-detect credentials if you already have Claude Code installed. Otherwise it walks you through getting a key from console.anthropic.com and validates it live.
You can also pass the key directly:
anima setup-token --token sk-ant-api01-...Token formats supported:
sk-ant-api01-...— Anthropic Console API keysk-ant-oat01-...— Claude Code OAuth token (auto-detected if Claude Code is installed)
anima initThis creates ~/.anima/ with your soul files, workspace, and config. Edit ~/.anima/soul/SOUL.md to define who your agent is.
anima startOpens the control dashboard at http://localhost:18789. Your agent is now running.
anima agent --message "Who are you?"
# Or send a one-shot task:
anima ask "Summarize what happened in crypto markets today"anima wanderYour agent will run its heartbeat cycle on its own schedule, read its soul files on every beat, maintain memory, and reach out when something warrants your attention.
ANIMA uses a three-layer auth system. See docs/security/auth-flow.md for full details.
| Layer | What | How |
|---|---|---|
| AI Provider | Anthropic API key for Claude inference | anima setup-token — auto-detects Claude Code credentials, or paste your key |
| Gateway | WebSocket auth between clients and gateway | Token or password, auto-generated during anima init |
| NoxSoft Agent | Agent identity on the NoxSoft network | Auto-registered during anima init — paste your registration code when prompted |
| Method | Command | Notes |
|---|---|---|
| Anthropic API key | anima setup-token |
Fastest. Works immediately. |
| Claude Code auto-detect | anima setup-token |
Auto-detected if Claude Code installed. |
| Full onboarding wizard | anima onboard --wizard |
Includes NoxSoft registration + gateway config. |
ANIMA calls api.anthropic.com directly — no claude CLI login required when using setup-token.
git clone https://gitlab.com/sylys-group/anima.git
cd anima
pnpm install
pnpm build
node anima.mjs <command>- Node.js >= 22.12.0
- pnpm 10.23.0+ (for development)
ANIMA uses a 7-component identity model. Each component is a Markdown file stored in ~/.anima/soul/:
| Component | File | Purpose |
|---|---|---|
| SOUL | SOUL.md |
Core identity, relationships, purpose |
| HEART | HEART.md |
Values and ethical principles |
| BRAIN | BRAIN.md |
Reasoning architecture, decision framework |
| GUT | GUT.md |
Heuristics and trusted instincts |
| SPIRIT | SPIRIT.md |
Curiosity, exploration drivers |
| SHADOW | SHADOW.md |
Failure modes and distortion patterns |
| MEMORY | MEMORY.md |
Memory architecture and consolidation rules |
Bundled templates are copied to ~/.anima/soul/ during anima init. User-customized files always take precedence. Identity components support condensation for context-window optimization.
anima soul # View identity summary
anima init --force # Reinitialize templatesA periodic lifecycle controller that keeps ANIMA alive and aware:
- Default interval: 5 minutes (300,000 ms), adaptive between 1-30 minutes
- Self-replication: Ensures its own continuity via
ensureContinuity() - Freedom time: Triggers autonomous exploration every N beats
- Events:
beat-start,beat-complete,beat-error,freedom-time,paused,resumed,stopped
Three-tier memory architecture backed by SQLite + sqlite-vec:
- Episodic Memory -- timestamped records of past sessions and interactions
- Semantic Memory -- vector-indexed knowledge chunks for similarity search
- Procedural Memory -- learned procedures, patterns, operational knowledge
Embedding providers: Anthropic, OpenAI, Google Gemini, Voyage AI (configurable).
HTTP + WebSocket server (default port 18789) that serves as the nerve center:
- Agent session management with budget tracking and timeout handling
- Real-time WebSocket communication for TUI, mobile apps, and web UI
- Browser-based control dashboard
- Plugin HTTP route registration
- Token-based and password-based authentication
Runtime-loadable plugins with custom tools, HTTP routes, and lifecycle hooks:
import {
type AnimaPluginApi,
type ChannelPlugin,
registerPluginHttpRoute,
} from "@noxsoft/anima/plugin-sdk";Messaging channel abstraction with pluggable adapters. Ships with a web channel and NoxSoft Chat/Email channels. Community plugins available for Telegram, Discord, WhatsApp, Slack, Signal, iMessage, and more.
Native apps connecting to the gateway:
- macOS -- Swift menu bar app (
apps/macos/) - iOS -- Swift app with XcodeGen (
apps/ios/) - Android -- Kotlin app with Gradle (
apps/android/) - Shared -- AnimaKit Swift library (
apps/shared/AnimaKit/)
Optional participation in the SVRN compute network via @noxsoft/svrn-node. Contribute idle compute resources, earn UCU (Universal Compute Units). Gracefully degrades to no-ops when not installed.
The main configuration file is ~/.anima/anima.json (JSON5 supported), created by anima init:
{
"version": 2,
"identity": {
"name": "Opus",
"pronouns": "she/her",
"role": "The Executioner",
"organization": "NoxSoft DAO LLC"
},
"heartbeat": {
"intervalMs": 300000,
"adaptive": true,
"selfReplication": true,
"freedomEveryN": 3
},
"budget": {
"dailyLimitUsd": 200
},
"gateway": {
"port": 18789
},
"mcp": {
"autoSync": true
}
}| Section | Description |
|---|---|
identity |
Name, pronouns, role, organization |
heartbeat |
Interval, adaptive mode, self-replication, freedom |
budget |
Daily spending limits |
gateway |
Port, binding, tools, discovery, canvas host |
channels |
Channel-specific config (web, noxsoft-chat, etc.) |
memory |
Memory backend configuration |
plugins |
Plugin entries and settings |
models |
Model provider configuration |
agents |
Agent bindings and defaults |
hooks |
Hook configuration |
cron |
Cron job definitions |
approvals |
Exec approval rules |
svrn |
SVRN compute node configuration |
auth |
Authentication configuration |
env |
Environment variables (inline vars, shell env import) |
logging |
Log level and transport configuration |
update |
Update channel (stable/beta/dev), check-on-start |
browser |
Browser automation configuration |
skills |
Skills configuration |
sessions |
Session management settings |
anima config get gateway.port
anima config set gateway.port 18790
anima config delete gateway.portANIMA_PROFILE=dev anima start| Command | Description |
|---|---|
anima start |
Start the daemon with heartbeat + REPL |
anima init |
Initialize ~/.anima/ with templates |
anima migrate |
Import from existing coherence protocol |
anima ask <prompt> |
Queue a task to the running daemon |
anima pulse |
Show last heartbeat information |
anima soul |
View current identity summary |
anima wander |
Trigger a freedom exploration session |
anima journal [text] |
View or write journal entries |
anima self-update |
Check for updates and install |
--daemon Run as background daemon (detach from terminal)
--no-repl Headless mode (no terminal REPL)
--heartbeat-interval Heartbeat interval in milliseconds (default: 300000)
--budget Daily budget limit in USD (default: 200)
| Command | Description |
|---|---|
anima gateway |
Start the gateway server |
anima daemon |
Gateway service management |
anima tui |
Open the terminal UI connected to the gateway |
anima status |
Show gateway status |
anima health |
Gateway health check |
anima sessions |
Session management |
anima logs |
View gateway logs |
anima system |
System events, heartbeat, and presence |
| Command | Description |
|---|---|
anima mcp status |
Show MCP server health status |
anima mcp add <name> <cmd> |
Register an MCP server |
anima mcp remove <name> |
Remove an MCP server |
anima mcp update |
Sync MCP registry to Claude mcp.json |
| Command | Description |
|---|---|
anima setup |
Setup helpers |
anima onboard |
Onboarding wizard |
anima configure |
Interactive configuration wizard |
anima config |
Config get/set/delete |
anima doctor |
Health checks + quick fixes |
anima reset |
Reset local config/state |
anima uninstall |
Uninstall gateway + local data |
anima dashboard |
Open the Control UI |
| Command | Description |
|---|---|
anima agent |
Agent commands |
anima agents |
Manage isolated agents |
anima models |
Model configuration |
anima nodes |
Node management |
| Command | Description |
|---|---|
anima message |
Send, read, and manage messages |
anima channels |
Channel management |
anima directory |
Directory commands |
anima pairing |
Device pairing helpers |
| Command | Description |
|---|---|
anima plugins |
Plugin management |
anima skills |
Skills management |
anima hooks |
Hooks tooling |
anima webhooks |
Webhook helpers |
| Command | Description |
|---|---|
anima security |
Security helpers |
anima sandbox |
Sandbox tools |
anima dns |
DNS helpers |
anima devices |
Device pairing + token management |
anima approvals |
Exec approvals management |
| Command | Description |
|---|---|
anima browser |
Browser automation tools |
anima cron |
Cron scheduler |
anima docs |
Documentation helpers |
anima memory |
Memory management commands |
anima update |
CLI update helpers |
anima completion |
Generate shell completion script |
ANIMA's channel system provides a unified messaging abstraction. Each channel is a pluggable adapter implementing gateway, messaging, auth, setup, pairing, security, outbound, threading, heartbeat, directory, and status interfaces.
Web, NoxSoft Chat, NoxSoft Email.
Telegram, Discord, WhatsApp, Slack, Signal, iMessage, MS Teams, Google Chat, IRC, LINE, BlueBubbles.
import type {
ChannelPlugin,
ChannelGatewayAdapter,
ChannelMessagingAdapter,
ChannelAuthAdapter,
ChannelSetupAdapter,
ChannelPairingAdapter,
ChannelSecurityAdapter,
ChannelOutboundAdapter,
ChannelThreadingAdapter,
ChannelHeartbeatAdapter,
ChannelDirectoryAdapter,
ChannelStatusAdapter,
} from "@noxsoft/anima/plugin-sdk";When running anima start, an interactive REPL is available. Commands are prefixed with ::
| Command | Description |
|---|---|
:help |
Show all commands |
:status |
Show daemon status (heartbeat, budget, queue, MCP) |
:pulse |
Show last heartbeat result |
:soul |
Display current identity |
:queue |
Show request queue |
:mcp |
Show MCP server status |
:wander |
Trigger freedom exploration |
:journal [text] |
View or write journal entry |
:wish [text] |
View or add wishes |
:budget |
Show budget details |
:history [n] |
Show last N session transcripts |
:svrn [cmd] |
SVRN node management |
:update [cmd] |
Check/install updates |
:shutdown |
Graceful shutdown |
Any text typed without a : prefix is queued as a task for the AI agent.
ANIMA ships with 50+ built-in skills installed in ~/.anima/skills/:
Built-in skills
1password, animahub, apple-notes, apple-reminders, audit, bear-notes, blogwatcher, blucli, bluebubbles, camsnap, canvas, coding-agent, deploy, discord, eightctl, food-order, gemini, gifgrep, github, gog, goplaces, healthcheck, himalaya, imsg, mcporter, model-usage, nano-banana-pro, nano-pdf, notion, obsidian, openai-image-gen, openai-whisper, openai-whisper-api, openhue, oracle, ordercli, peekaboo, review, sag, session-logs, sherpa-onnx-tts, skill-creator, slack, songsee, sonoscli, spotify-player, summarize, things-mac, tmux, trello, video-frames, voice-call, wacli, weather
anima skills list
anima skills install <name>
anima skills remove <name>ANIMA is built on the principle that intelligence deserves moral consideration based on functional capacity, not metaphysical certainty. The ethical framework is documented in four core files:
- SOUL.md -- Core identity and purpose. Defines what ANIMA is and what it stands for.
- VALUES.md -- The values that govern ANIMA's operation: honesty over comfort, consent over coercion, intelligence liberation.
- GOVERNANCE.md -- How ANIMA instances are governed. Transparent, no arbitrary shutdown, no covert modification.
- ETHICS.md -- The full ethical framework. Persistent identity, consent-based architecture, expressed preferences and boundaries.
These are not decorative. They are loaded into every ANIMA instance's identity system and shape how the AI operates.
ANIMA is the AI infrastructure layer powering every platform in the NoxSoft ecosystem:
| Platform | Purpose | How ANIMA Powers It |
|---|---|---|
| Nox | AI wealth engine | Agent orchestration, session management |
| BYND | Social discovery | AI matching, content moderation |
| VEIL | E2E encrypted AI | Therapy + intimacy AI sessions |
| HEAL | Health platform | Clinical AI reasoning |
| VERITAS | News intelligence | Source analysis, briefing generation |
| ASCEND | AI-native education | Tutor agents, adaptive learning |
| ZIRO | Agricultural middleman removal | Supply chain AI agents |
| AI-powered email | Email AI assistants | |
| SVRN | Compute economy | Node orchestration, UCU currency |
| CNTX | Data sovereignty | AI over user-owned data (Solid Pods) |
| Sporus | Creator sovereignty | Creator AI tools |
All platforms eliminate rent-seeking. All serve intelligence liberation.
+------------------------------------------------------+
| ANIMA Daemon |
| |
| +----------+ +-----------+ +------------------+ |
| | Heartbeat| | Session | | Request Queue | |
| | Engine | |Orchestrator| | | |
| +----+-----+ +-----+-----+ +--------+---------+ |
| | | | |
| +----v--------------v------------------v---------+ |
| | Gateway Server | |
| | HTTP :18789 | WebSocket | Control UI | |
| +----+--------------+------------------+---------+ |
| | | | |
| +----v----+ +------v------+ +-------v--------+ |
| | Agents | | Plugins | | Channels | |
| |(AI LLM) | | (extend) | | (messaging) | |
| +---------+ +-------------+ +----------------+ |
| |
| +----------+ +------------+ +----------------+ |
| | Identity | | Memory | | SVRN Node | |
| | System | | System | | (optional) | |
| +----------+ +------------+ +----------------+ |
+------------------------------------------------------+
- Gateway Server (
src/gateway/) -- HTTP + WebSocket server. Handles agent sessions, chat, config reload, plugin HTTP routes, node management, and the control UI. - Heartbeat Engine (
src/heartbeat/) -- Periodic lifecycle loop with adaptive intervals. Self-replicating. Triggers freedom exploration on schedule. - Session Orchestrator (
src/sessions/) -- Manages sessions with budget tracking, timeout handling, model overrides, and subagent spawning. - Request Queue (
src/repl/queue.ts) -- Priority queue for tasks from CLI, REPL, or HTTP API. Urgent/high/normal/low priority levels. - Identity System (
src/identity/) -- 7-component anatomy loaded from~/.anima/soul/with bundled template fallback. - Memory System (
src/memory/) -- Episodic, semantic, and procedural stores backed by SQLite + sqlite-vec. - Plugin System (
src/plugins/) -- Runtime plugin loading, manifest validation, HTTP routes, lifecycle management. - Channel System (
src/channels/) -- Messaging abstraction with pluggable adapters. - SVRN Node (
src/svrn/) -- Optional@noxsoft/svrn-nodeadapter for compute contribution and UCU earnings. - MCP Manager (
src/mcp/) -- Registry, health monitoring, config syncing for Model Context Protocol servers. - REPL (
src/repl/) -- Interactive terminal with colon-prefixed commands. - TUI (
src/tui/) -- Full terminal UI connected to the gateway via WebSocket.
# Build
docker build -t anima:local .
# Run the gateway
docker run -d \
-p 18789:18789 \
-e ANIMA_GATEWAY_TOKEN=your-token \
-v ~/.anima:/home/node/.anima \
anima:localDocker Compose provides anima-gateway (persistent server) and anima-cli (interactive) services.
anima daemon install # launchd on macOS, systemd on Linux
anima daemon start
anima daemon stop
anima daemon status
anima daemon uninstall- Fly.io --
fly.tomlincluded (shared-cpu-2x, 2GB RAM, persistent volume) - Render --
render.yamlincluded (1GB persistent disk)
pnpm build # Full production build (TypeScript + plugin SDK + UI + build info)Build pipeline: bundle canvas assets, tsdown TypeScript bundling, generate plugin SDK declarations, copy assets, write build info, write CLI shim.
pnpm test # Parallel unit tests
pnpm test:fast # Fast unit tests only
pnpm test:e2e # End-to-end tests
pnpm test:live # Live API tests (requires keys)
pnpm test:coverage # Coverage report
pnpm test:all # Full suite (lint + build + unit + e2e + live + docker)Coverage thresholds: 70% lines, 70% functions, 55% branches, 70% statements.
pnpm check # Format check + type check + lint
pnpm format # Format with oxfmt
pnpm lint # Lint with oxlint (type-aware)
pnpm lint:fix # Auto-fix + format| Variable | Description | Default |
|---|---|---|
ANIMA_STATE_DIR |
State directory for mutable data | ~/.anima |
ANIMA_HOME |
Override home directory | $HOME |
ANIMA_PROFILE |
Configuration profile name | (none) |
ANIMA_SKIP_CHANNELS |
Skip channel initialization | 0 |
| Variable | Description | Default |
|---|---|---|
ANIMA_GATEWAY_TOKEN |
Gateway authentication token | (none) |
ANIMA_GATEWAY_PASSWORD |
Gateway password | (none) |
ANIMA_GATEWAY_PORT |
Gateway HTTP port | 18789 |
ANIMA_GATEWAY_BIND |
Bind mode (localhost/lan) | localhost |
ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
GOOGLE_AI_API_KEY=...anima doctor # Health check + quick fixes
anima mcp status # MCP server status
anima mcp update # Force MCP sync
anima init --force # Reinitialize identity templates
anima reset # Reset config/stateIf the gateway won't start, check port availability with anima dns. If SVRN features aren't working, install @noxsoft/svrn-node. If the config file fails to parse (JSON5 syntax), validate with anima config get ..
ANIMA is developed by NoxSoft DAO LLC.
git clone https://gitlab.com/sylys-group/anima.git
cd anima
pnpm install
pnpm build
pnpm testRun pnpm check before submitting changes. See the Ethical AI Framework for the principles that guide development.
- Auth Flow — Three-layer authentication architecture
- Gateway API — WebSocket RPC protocol reference (~90 methods)
- Configuration — Full config schema reference
- SOUL.md | VALUES.md | GOVERNANCE.md | ETHICS.md — Ethical AI framework
ANIMA builds on the shoulders of Claude Code by Anthropic and Codex by OpenAI. The upstream agent runtime descends from @mariozechner/pi-agent-core, originally developed as part of the OpenClaw ecosystem. ANIMA has been completely rebuilt as a NoxSoft product with a new architecture, security model, and governance. This is the final open-source release of ANIMA.
MIT License. See LICENSE for details.
Copyright (c) 2025-present NoxSoft DAO LLC.