Installation

Installation

Complete setup guide for aistack with troubleshooting

Prerequisites

Before installing aistack, ensure you have:

• Node.js 20.0.0 or higher
• npm (comes with Node.js)
• Claude Code (for MCP integration)
• API Keys (at least one):
  • Anthropic API key (ANTHROPIC_API_KEY)
  • OpenAI API key (OPENAI_API_KEY)
  • Or a local Ollama instance

Quick Installation

1. Install the Package

npm install @blackms/aistack

2. Initialize Project

npx @blackms/aistack init

This creates:

• aistack.config.json - Configuration file
• data/ - Database directory
• plugins/ - Plugin directory (empty)

3. Configure API Keys

Create a .env file in your project root:

# Required: At least one LLM provider
ANTHROPIC_API_KEY=your_anthropic_api_key_here
OPENAI_API_KEY=your_openai_api_key_here

# Optional: For authentication
JWT_SECRET=your_random_secret_here

# Optional: For GitHub integration
GITHUB_TOKEN=your_github_token_here

Update aistack.config.json:

{
  "version": "1.0.0",
  "providers": {
    "default": "anthropic",
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "model": "claude-sonnet-4-20250514"
    },
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "gpt-4o"
    },
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "model": "llama3.2"
    }
  },
  "memory": {
    "path": "./data/aistack.db",
    "vectorSearch": {
      "enabled": false,
      "provider": "openai"
    }
  },
  "auth": {
    "enabled": true,
    "jwtSecret": "${JWT_SECRET}"
  }
}

4. Verify Installation

npx @blackms/aistack status

Expected output:

✓ Config loaded
✓ Database initialized
✓ Agents: 0 active
✓ Memory: 0 entries
✓ System: healthy

Integration with Claude Code

Add to Claude Code MCP Configuration

claude mcp add aistack -- npx @blackms/aistack mcp start

This adds aistack to your Claude Code MCP configuration. Verify by checking:

claude mcp list

You should see aistack in the list.

Start the MCP Server

The MCP server starts automatically when Claude Code launches. To test manually:

npx @blackms/aistack mcp start

Optional: Web Dashboard

Start the web dashboard for visual management:

npx @blackms/aistack web start

Open http://localhost:3001 in your browser.

Installation Methods

Global Installation

npm install -g @blackms/aistack
aistack init
aistack status

Project-Local Installation

npm install --save-dev @blackms/aistack

From Source

git clone https://github.com/blackms/aistack.git
cd aistack
npm install
npm run build
npm link

Platform-Specific Instructions

macOS

# Install Node.js via Homebrew
brew install node@20

# Install aistack
npm install @blackms/aistack

Linux

# Install Node.js via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# Install aistack
npm install @blackms/aistack

Windows

# Install Node.js from https://nodejs.org
# Then install aistack
npm install @blackms/aistack

LLM Provider Setup

Anthropic (Recommended)

1. Get API key from https://console.anthropic.com
2. Add to .env:

   ANTHROPIC_API_KEY=sk-ant-...
   

3. Set as default in config:

   {
     "providers": {
       "default": "anthropic"
     }
   }

OpenAI

1. Get API key from https://platform.openai.com
2. Add to .env:

   OPENAI_API_KEY=sk-...
   

3. Supports embeddings for vector search

Ollama (Local)

1. Install Ollama from https://ollama.ai
2. Pull a model:

   ollama pull llama3.2

3. Configure in aistack.config.json:

   {
     "providers": {
       "ollama": {
         "baseUrl": "http://localhost:11434",
         "model": "llama3.2"
       }
     }
   }

Troubleshooting

Error: "Cannot find module '@blackms/aistack'"

Solution: Ensure you've installed the package:

npm install @blackms/aistack

Error: "ANTHROPIC_API_KEY not found"

Solution: Create a .env file with your API key or set the environment variable:

export ANTHROPIC_API_KEY=your_key_here

Error: "Database file not found"

Solution: Run initialization:

npx @blackms/aistack init

Error: "Port 3001 already in use"

Solution: Change the port in config or kill the process:

# Find process
lsof -ti:3001
# Kill it
kill -9 <PID>

MCP Server Not Showing in Claude Code

Solution: Check MCP configuration:

claude mcp list
claude mcp add aistack -- npx @blackms/aistack mcp start

Vector Search Not Working

Solution: Enable vector search in config and ensure OpenAI or Ollama is configured:

{
  "memory": {
    "vectorSearch": {
      "enabled": true,
      "provider": "openai"
    }
  }
}

Next Steps

• Quick Start Tutorial - Get started in 5 minutes
• Configuration Guide - Detailed configuration options
• First Agent Tutorial - Spawn your first agent

Upgrading

From v1.2.x to v1.3.x

npm update @blackms/aistack

The database schema is backward compatible. No migration needed.

Breaking Changes

Check the CHANGELOG for breaking changes between versions.

Uninstalling

# Remove package
npm uninstall @blackms/aistack

# Remove configuration and data
rm -rf aistack.config.json data/ plugins/

Support

If you encounter issues:

• Check Troubleshooting guide
• Search GitHub Issues
• Ask in Discussions

---

See Also

• Configuration Guide
• Troubleshooting
• CLI Commands