Installation

Platform-specific installation instructions for Animus.

System Requirements

Requirement Minimum Recommended
Node.js 25.0.0 Latest LTS
npm 11.0.0 Latest
RAM 2 GB 4 GB+
Disk 500 MB 2 GB+
OS macOS, Linux, Windows macOS or Linux

macOS

Desktop Application

Download the .dmg from the downloads page and drag Animus to your Applications folder. The desktop app bundles Node.js, the engine, the interface, and all databases. No additional setup required.

Desktop builds are coming soon. In the meantime, use the From Source method below.

From Source

Install Node.js 25+ and then clone and install:

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

Windows

Desktop Application

Download the .exe installer from the downloads page. The installer bundles everything Animus needs. No additional setup required.

Desktop builds are coming soon. In the meantime, use the From Source method below.

From Source

Install Node.js using winget:

winget install OpenJS.NodeJS

Then in PowerShell:

git clone https://github.com/craigtut/animus.git
cd animus
npm install
Copy-Item .env.example .env

Note: Animus works on Windows but is primarily developed and tested on macOS and Linux. Some file-watching features may behave differently.

Linux

Ubuntu / Debian

# Install Node.js 25 via NodeSource
curl -fsSL https://deb.nodesource.com/setup_25.x | sudo -E bash -
sudo apt-get install -y nodejs

# Clone and install
git clone https://github.com/craigtut/animus.git
cd animus
npm install
cp .env.example .env

Arch Linux

sudo pacman -S nodejs npm
git clone https://github.com/craigtut/animus.git
cd animus
npm install
cp .env.example .env

Docker

Animus does not have an official Docker image yet, but it ships with a Dockerfile and Docker Compose configuration. You can build and run it locally.

Prerequisites

Setup

Clone the repository:

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

Copy the environment file:

cp .env.example .env

The defaults work for Docker. If you want to pre-configure an API key, edit .env and set ANTHROPIC_API_KEY or OPENAI_API_KEY. Otherwise, you can configure credentials through the web interface after launch.

Customizing the Compose File

The default docker-compose.yml exposes port 3000 and maps ./data for persistent storage:

services:
  animus:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    env_file:
      - .env
    restart: unless-stopped

Common customizations:

  • Change the port: Replace "3000:3000" with "8080:3000" to access Animus on port 8080
  • Change the data directory: Replace ./data:/app/data with your preferred path (e.g., /mnt/storage/animus:/app/data)
  • Set resource limits: Use a docker-compose.override.yml to add memory limits or other deployment-specific settings

An example override file is included at docker-compose.override.yml for reference.

Build and Run

docker compose up --build -d

The first build takes several minutes as it compiles native dependencies. Subsequent starts are fast.

Access the Interface

Open http://localhost:3000 in your browser. The onboarding flow will guide you through provider setup and persona creation.

To view logs:

docker compose logs -f

To stop the container:

docker compose down

Persistent data (databases, models, media) is stored in the ./data directory and survives container restarts.

Verify Installation

After installation (any method), verify everything is working:

npm run dev

You should see:

[backend]  Server listening on http://localhost:3000
[frontend] Local: http://localhost:5173
[backend]  Heartbeat started (interval: 300000ms)

Open http://localhost:5173 and confirm the presence page loads.

Troubleshooting

`npm install` fails with native module errors

Some dependencies (better-sqlite3, LanceDB bindings) require native compilation. Make sure you have build tools installed:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt-get install build-essential python3

# Windows
npm install -g windows-build-tools

Port already in use

If port 3000 or 5173 is taken, you can configure alternatives in your .env:

PORT=3001

Docker build fails on ARM Mac

If you're building on an Apple Silicon Mac for a different architecture (e.g., an x86_64 server), use Docker buildx:

docker buildx build --platform linux/amd64 -t animus-engine . --load

Next Steps