Skip to content

Configuration Guide

Jump to bottom
Alessio Rocchi edited this page Jan 27, 2026 · 1 revision

Configuration Guide

Complete guide to configuring aistack for your environment.

Table of Contents

Configuration File

aistack uses a JSON configuration file located at aistack.config.json in your project root.

Creating the Configuration File

# Initialize creates a default config
npx @blackms/aistack init

# Or create manually
touch aistack.config.json

Basic Configuration Structure

{
  "version": "1.0.0",
  "providers": { },
  "memory": { },
  "agents": { },
  "github": { },
  "plugins": { },
  "mcp": { },
  "auth": { },
  "hooks": { }
}

Environment Variables

Using Environment Variables

aistack supports environment variable interpolation using ${VAR_NAME} syntax:

{
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  }
}

Required Environment Variables

# Anthropic (if using)
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# OpenAI (if using)
export OPENAI_API_KEY="sk-..."

# GitHub (if using token auth)
export GITHUB_TOKEN="ghp_..."

# JWT Secret (if using auth)
export JWT_SECRET="your-secret-key-min-32-chars"

Optional Environment Variables

# Ollama base URL (default: http://localhost:11434)
export OLLAMA_BASE_URL="http://localhost:11434"

# Database path (default: ./data/aistack.db)
export AISTACK_DB_PATH="./data/aistack.db"

# Log level (default: info)
export LOG_LEVEL="debug"

.env File Support

Create a .env file in your project root:

# .env
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-...
GITHUB_TOKEN=ghp_...
JWT_SECRET=your-secret-key-min-32-chars

Load with dotenv:

npm install dotenv
// In your script
require('dotenv').config();

Provider Configuration

Anthropic

{
  "providers": {
    "default": "anthropic",
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "model": "claude-sonnet-4-20250514",
      "maxTokens": 4096,
      "temperature": 0.7
    }
  }
}

Available Models:

  • claude-sonnet-4-20250514 (default, recommended)
  • claude-opus-4-20241229
  • claude-3-5-sonnet-20241022

OpenAI

{
  "providers": {
    "default": "openai",
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "gpt-4o",
      "maxTokens": 4096,
      "temperature": 0.7
    }
  }
}

Available Models:

  • gpt-4o (default)
  • gpt-4o-mini
  • gpt-4-turbo
  • gpt-3.5-turbo

Ollama (Local)

{
  "providers": {
    "default": "ollama",
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "model": "llama3.2",
      "maxTokens": 4096,
      "temperature": 0.7
    }
  }
}

Popular Models:

  • llama3.2 (default)
  • codellama
  • mistral
  • mixtral

CLI Providers

{
  "providers": {
    "default": "claude-code",
    "cliProviders": {
      "claudeCode": {
        "model": "sonnet"
      },
      "gemini": {
        "model": "gemini-2.0-flash"
      }
    }
  }
}

Multiple Providers

{
  "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 Configuration

Basic Memory Setup

{
  "memory": {
    "path": "./data/aistack.db",
    "defaultNamespace": "default"
  }
}

With Vector Search

{
  "memory": {
    "path": "./data/aistack.db",
    "defaultNamespace": "default",
    "vectorSearch": {
      "enabled": true,
      "provider": "openai",
      "model": "text-embedding-3-small",
      "dimensions": 1536
    }
  }
}

Vector Search Providers:

  • openai - Uses OpenAI embedding API
  • ollama - Uses Ollama embeddings (local)

OpenAI Embedding Models:

  • text-embedding-3-small (1536 dims, default)
  • text-embedding-3-large (3072 dims)

Ollama Embedding Models:

  • nomic-embed-text (768 dims, default)
  • mxbai-embed-large (1024 dims)

Database Configuration

{
  "memory": {
    "path": "./data/aistack.db",
    "defaultNamespace": "default",
    "options": {
      "verbose": false,
      "fileMustExist": false,
      "timeout": 5000
    }
  }
}

Agent Configuration

{
  "agents": {
    "maxConcurrent": 10,
    "defaultTimeout": 300,
    "retryAttempts": 3,
    "retryDelay": 1000
  }
}

Options:

  • maxConcurrent - Maximum concurrent agents (1-20, default: 10)
  • defaultTimeout - Default timeout in seconds (10-3600, default: 300)
  • retryAttempts - Number of retry attempts (0-10, default: 3)
  • retryDelay - Delay between retries in ms (100-10000, default: 1000)

GitHub Configuration

Using gh CLI (Recommended)

{
  "github": {
    "enabled": true,
    "useGhCli": true
  }
}

Requires gh CLI to be authenticated:

gh auth login

Using Token

{
  "github": {
    "enabled": true,
    "useGhCli": false,
    "token": "${GITHUB_TOKEN}"
  }
}

Disabled

{
  "github": {
    "enabled": false
  }
}

Plugin Configuration

Enable Plugins

{
  "plugins": {
    "enabled": true,
    "directory": "./plugins",
    "autoload": true
  }
}

Disable Plugins

{
  "plugins": {
    "enabled": false
  }
}

MCP Configuration

stdio Transport (Default)

{
  "mcp": {
    "transport": "stdio"
  }
}

HTTP Transport

{
  "mcp": {
    "transport": "http",
    "port": 3000,
    "host": "localhost"
  }
}

Authentication Configuration

Enable Authentication

{
  "auth": {
    "enabled": true,
    "jwtSecret": "${JWT_SECRET}",
    "accessTokenExpiry": "15m",
    "refreshTokenExpiry": "7d"
  }
}

Disable Authentication

{
  "auth": {
    "enabled": false
  }
}

Token Expiry Formats:

  • 15m - 15 minutes
  • 1h - 1 hour
  • 7d - 7 days
  • 30d - 30 days

Configuration Validation

Validate Configuration

npx @blackms/aistack validate-config

Programmatic Validation

import { validateConfig, loadConfig } from '@blackms/aistack';

const config = loadConfig('./aistack.config.json');
const { valid, errors } = validateConfig(config);

if (!valid) {
  console.error('Configuration errors:', errors);
  process.exit(1);
}

Common Validation Errors

Missing API Key:

Error: providers.anthropic.apiKey is required

Fix: Set ANTHROPIC_API_KEY environment variable

Invalid Path:

Error: memory.path must be a valid file path

Fix: Use absolute or relative path: ./data/aistack.db

Invalid Port:

Error: mcp.port must be between 1024 and 65535

Fix: Use valid port number: 3000

Best Practices

Security

  1. Never commit API keys to version control
# Add to .gitignore
echo "aistack.config.json" >> .gitignore
echo ".env" >> .gitignore
  1. Use environment variables
{
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  }
}
  1. Restrict file permissions
chmod 600 aistack.config.json
chmod 600 .env
chmod 600 ./data/aistack.db

Performance

  1. Limit concurrent agents
{
  "agents": {
    "maxConcurrent": 5
  }
}
  1. Set appropriate timeouts
{
  "agents": {
    "defaultTimeout": 300
  }
}
  1. Enable vector search for large datasets
{
  "memory": {
    "vectorSearch": {
      "enabled": true,
      "provider": "openai"
    }
  }
}

Development vs Production

Development:

{
  "providers": {
    "default": "ollama",
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "model": "llama3.2"
    }
  },
  "memory": {
    "path": "./data/dev.db"
  },
  "auth": {
    "enabled": false
  }
}

Production:

{
  "providers": {
    "default": "anthropic",
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "model": "claude-sonnet-4-20250514"
    }
  },
  "memory": {
    "path": "/var/lib/aistack/prod.db",
    "vectorSearch": {
      "enabled": true,
      "provider": "openai"
    }
  },
  "auth": {
    "enabled": true,
    "jwtSecret": "${JWT_SECRET}"
  }
}

Complete Example

{
  "version": "1.0.0",
  "providers": {
    "default": "anthropic",
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "model": "claude-sonnet-4-20250514",
      "maxTokens": 4096,
      "temperature": 0.7
    },
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "gpt-4o"
    },
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "model": "llama3.2"
    }
  },
  "memory": {
    "path": "./data/aistack.db",
    "defaultNamespace": "default",
    "vectorSearch": {
      "enabled": true,
      "provider": "openai",
      "model": "text-embedding-3-small"
    }
  },
  "agents": {
    "maxConcurrent": 10,
    "defaultTimeout": 300,
    "retryAttempts": 3
  },
  "github": {
    "enabled": true,
    "useGhCli": true
  },
  "plugins": {
    "enabled": true,
    "directory": "./plugins",
    "autoload": true
  },
  "mcp": {
    "transport": "stdio"
  },
  "auth": {
    "enabled": true,
    "jwtSecret": "${JWT_SECRET}",
    "accessTokenExpiry": "15m",
    "refreshTokenExpiry": "7d"
  },
  "hooks": {
    "sessionStart": true,
    "sessionEnd": true,
    "preTask": true,
    "postTask": true
  }
}

Next Steps

Related:

Home

Getting Started

Core Concepts

Agent Guides

MCP Tools

Recipes

Advanced

Reference

Clone this wiki locally