Documentation

Self-Hosted Installation

A1KnowHow Personal runs on your own machine. You keep the data, choose the models, and use the install zip that includes the binary plus setup scripts.

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

Linux or macOS (ARM64 builds below). Personal defaults to local Ollama models (lfm2.5 for chat and titles, embeddinggemma for embeddings), so plan RAM and disk for those.

Memory (RAM):

  • Minimum: 8GB RAM (CPU-only)
  • Recommended: 16GB+ RAM

Storage:

  • Several GB for the two default Ollama models, plus space for pb_data and document files

GPU (optional):

  • NVIDIA CUDA, AMD ROCm, or Apple Silicon Metal — faster chat; CPU-only still works

Notes:

  • Default models are sized for local hardware. Quality is lower than large cloud models; they are fine for Q&A, chat, and search on your own docs.
  • Prefer cloud LLM providers in config.yaml when you need stronger reasoning and accept sending prompts off-box. See MCP Servers & LLMs.

Quick Start

  1. Download the Personal install zip for your platform
  2. Unzip and enter the folder
  3. Install Ollama and pull the default models (see Dependencies)
  4. Edit config.yaml if needed (app.url, LLM, importer)
  5. Run ./setup.sh, then ./run.sh

Download

macOS (Apple Silicon)

M1, M2, M3, M4
ARM64

Linux (ARM64)

Raspberry Pi 4/5
ARM servers

Each download is a zip containing a1kh, config.yaml, setup.sh, and run.sh.

unzip a1kh-personal-*.zip
cd a1kh-personal-*
chmod +x setup.sh run.sh
# pull Ollama models first — see Dependencies
./setup.sh
./run.sh

Open app.url from config.yaml (default http://localhost:8383) and sign in with the User account printed by setup.

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 choose Open anyway

What setup does

./setup.sh creates secrets/encryption_key if missing, prompts for PocketBase admin and app user credentials, runs migrate + seed (workflow templates, bootstrap workspaces, agents, starter docs), and prints a green summary — save those passwords.

Non-interactive:

[email protected] ADMIN_PASSWORD='...' [email protected] USER_PASSWORD='...' ./setup.sh

Vector search uses built-in sqlite-vec (no separate vector database). PDF/Office import needs Docling later — the shipped config uses importer.provider: none until you enable it.

Optional: Docker for dependencies

Run Ollama (and Docling if you need PDF/Office) in Docker while the app stays on the host via the install zip. See Docker Setup.

What’s Included

  • Upload and manage documents (markdown and plain text out of the box; PDF/Office with Docling)
  • Create and edit documents with AI assistance
  • AI agents, chat with documents, and semantic search
  • Workspaces, skills, and starter workflows from bootstrap seed
  • Local LLM via Ollama and embedded sqlite-vec

Next Steps

  1. Dependencies — Ollama (required) and Docling (optional)
  2. Configuration — config.yaml and secrets
  3. Docker Setup — optional containers for Ollama / Docling
  4. Features — using A1KnowHow after install