Getting Started

Get Animus running on your machine in under five minutes.

Prerequisites

Before installing Animus, make sure you have:

You can verify your setup:

node --version   # v25.0.0 or higher
npm --version    # 11.0.0 or higher

No API keys are needed to install and launch Animus. Provider credentials (Anthropic, OpenAI, etc.) are configured through the onboarding flow when you first open the interface.

Quick Install

Clone the repository and install dependencies:

git clone https://github.com/craigtut/animus.git
cd animus
npm install

Copy the example environment file:

cp .env.example .env

The defaults work out of the box. See the Configuration page for advanced options.

Start the Engine

Run both the backend and frontend in development mode:

npm run dev

This starts:

Service URL Purpose
Backend http://localhost:3000 API server and heartbeat
Frontend http://localhost:5173 Web interface

Open http://localhost:5173 in your browser. On first launch, the onboarding flow will walk you through choosing an AI provider, entering credentials, and creating your first persona.

What Happens Next

Once setup is complete, the engine begins its heartbeat loop, ticking every five minutes by default. During each tick, Animus:

  1. Gathers context from memory, goals, and active conversations
  2. Runs a mind session to think, reflect, and decide
  3. Executes any actions it chooses (responding to messages, updating goals, etc.)

You can watch this process in real time on the Mind page of the web interface.

Next Steps