Documentation

Self-Hosted Installation

A1KnowHow Self-Hosted edition allows you to run the complete knowledge base system on your own infrastructure. You maintain full control over your data, privacy, and configuration while enjoying all core features.

Why Self-Hosted?

  • Full Data Control: Your data stays on your servers
  • Privacy: No data leaves your infrastructure
  • Free: Open source and free to use
  • Customization: Configure and extend as needed
  • No Vendor Lock-in: You own your deployment

System Requirements

A1KnowHow requires a modern system with adequate resources to run local AI models. Basic requirements: Linux/macOS/Windows, 4GB RAM, and 20GB free disk space.

AI/LLM Requirements

Running local LLMs (Qwen3 and EmbeddingGemma) requires additional resources:

Memory (RAM):

  • Minimum: 8GB RAM (for CPU-only operation)
  • Recommended: 16GB+ RAM (for better performance)

Storage:

  • Model files: ~15GB free space for:
    • granite4.1:3b chat model (~4GB)
    • Qwen3:0.6B title generator (~0.5GB)
    • EmbeddingGemma embedding model (~1-2GB)
    • Additional space for model cache, vector database, and application data

GPU (Optional but Recommended):

  • With GPU: Significantly faster inference, especially for chat responses
    • NVIDIA: CUDA-compatible GPU with 4GB+ VRAM (recommended for granite4.1:3b)
    • AMD: ROCm-compatible GPU
    • Apple Silicon: Native Metal acceleration
  • CPU-only: Fully functional but responses will be slower (2-10x slower depending on CPU)

CPU:

  • Modern multi-core processor recommended
  • AVX512 support beneficial but not required

Important Notes:

  • Model Quality: The default models (granite4.1:3b and Qwen3:0.6B) are small models optimized for local deployment. While they provide good performance for their size, don’t expect the same quality as larger commercial models (e.g., GPT-5, Claude). They can be used for document Q&A, basic chat, and semantic search (albeit much slower), and will have limitations with complex reasoning tasks.
  • Performance Trade-offs: Smaller models enable local deployment on consumer hardware but come with quality and capability limitations compared to larger models.

Cloud Providers (Alternative to Local Models)

Consider using cloud providers when possible to access more powerful models without local hardware requirements:

AWS Bedrock (Currently Supported):

  • Access to high-quality models (e.g., Amazon Nova, Claude, Llama) without local GPU/VRAM requirements
  • Better quality for complex reasoning tasks compared to small local models
  • Requires AWS credentials (access key, secret key, and region)
  • Pay-per-use pricing model
  • Configure via config.yaml (see Configuration)

When to Use Cloud vs Local:

  • Use Cloud Providers: For better model quality, complex reasoning tasks, or when you don’t have sufficient local hardware
  • Use Local Models: For complete privacy, offline operation, sensitive data, or to avoid usage costs
  • Hybrid Approach: Use cloud for research/non-sensitive workspaces and local models for private/sensitive data

See MCP Servers & LLMs documentation for detailed configuration instructions.

Quick Start

  1. Download the A1KnowHow binary for your platform
  2. Install Dependencies: Set up Qdrant, Docling-serve, and Ollama (see Dependencies)
  3. Configure: Create config.yaml and secret files (see Configuration)
  4. Run: Start the application

Download Binary

macOS (Apple Silicon)

M1, M2, M3, M4
ARM64

Linux (ARM64)

Raspberry Pi 4/5
ARM servers

Note: On macOS Sequoia and later, you might get an error when running the binary, to fix this:

  1. Open System Settings,
  2. In search bar, type blocked app
  3. Select Privacy & Security
  4. Click Allow Anyway for the blocked app
  5. Rerun the binary, and chose Open anyway

Installation Methods

Docker (Recommended)

The easiest way to get started is using Docker and docker-compose. See our Docker Setup Guide for detailed instructions.

Manual Installation

For manual installation:

  1. Download the binary for your platform from the releases page
  2. Make it executable: chmod +x a1knowhow
  3. Create config file: Copy example-personal.config.yaml to config.yaml and set up secret files (see Configuration)
  4. Create data directory: mkdir -p pb_data
  5. Run the application: 
    ./a1knowhow --dir ./pb_data --config config.yaml serve

What’s Included

The self-hosted edition includes all core features:

  • Upload and manage documents (PDF, DOC, etc.)
  • Create and edit documents with AI assistance
  • AI agents, chat with documents, and semantic search
  • Organise content with workspaces
  • Local LLM models (Qwen3, EmbeddingGemma)
  • Docker and docker-compose support

Next Steps

  1. Read about Dependencies you’ll need to install
  2. Follow the Docker Setup guide for the easiest installation
  3. Review Configuration for your setup

Getting Help

  • Check the Features documentation to learn how to use A1KnowHow
  • Community support available
  • Open source - contribute and customise as needed