LinuxaiTested on real hardware

Karakeep With Local-AI Tagging (Ollama, No Cloud)

Install Karakeep on a Debian LXC and wire it to a local Ollama model for automatic, private bookmark tagging — plus the plain-output setting small models need.

DistrosDebian 12, Ubuntu 24.04
Shellbash
Updated
Script
bash
# Install Karakeep (self-hosted bookmark manager, formerly Hoarder) natively on
# Debian 12 / Ubuntu 24.04 and wire local-AI tagging via an Ollama endpoint.
# Full walkthrough: /blog/karakeep-local-ai-bookmarks

# 1. Run the OFFICIAL Linux install script (installs deps except Ollama,
#    Karakeep + Meilisearch, low-priv users, systemd units; also updates).
#    Run as root or with sudo.
wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/karakeep-linux.sh
bash karakeep-linux.sh
# Web UI now on http://<this-host>:3000 — create your first account in the browser.

# 2. Wire local-AI tagging. Edit the Karakeep env file (Debian install:
#    /etc/karakeep/karakeep.env) and add the block below, then restart.
#    Point OLLAMA_BASE_URL at your Ollama server's REAL address, never localhost.
cat >> /etc/karakeep/karakeep.env <<'EOF'
OLLAMA_BASE_URL=http://10.0.0.40:11434
INFERENCE_TEXT_MODEL=gemma3:4b
INFERENCE_IMAGE_MODEL=gemma3:4b
INFERENCE_CONTEXT_LENGTH=4096
INFERENCE_JOB_TIMEOUT_SEC=600
# Small local models choke on strict schema output -> use plain.
INFERENCE_OUTPUT_SCHEMA=plain
# Older Karakeep releases used the (now-deprecated) equivalent:
# INFERENCE_SUPPORTS_STRUCTURED_OUTPUT=false
EOF

# 3. Restart the workers (they run the tagging jobs) and the web app.
systemctl restart karakeep-workers karakeep-web

# 4. Acceptance: save a bookmark in the UI and watch a tag land. On CPU-only
#    hardware expect ~1-3 minutes per bookmark; confirm the calls are local:
#    tail -f /var/log/karakeep/karakeep-workers.log

What this does

This installs Karakeep — a self-hosted “bookmark everything” manager (formerly Hoarder) — on a bare-metal Debian 12 / Ubuntu 24.04 host (I use a Proxmox LXC) using its official Linux install script, then wires automatic tagging to a local Ollama model so no bookmark data or tag ever touches a cloud API. The install script also sets up Meilisearch for full-text search and registers everything as systemd services.

The full story — including why small local models need the plain-output setting and the install gotchas — is in Self-Hosted Bookmarks That Tag Themselves With Local AI.

Prerequisites

  • A Debian 12 or Ubuntu 24.04 host (the script’s supported targets). 2 CPU / 4 GB RAM / 30 GB disk is a comfortable floor — the headless browser and archiving want the memory.
  • An Ollama server reachable on your network with a model pulled (e.g. ollama pull gemma3:4b). A multimodal model covers both text and image tagging.
  • Outbound internet from the host (to fetch bookmarked pages and metadata).

Notes

  • Make these values your own before you rely on the result: replace 10.0.0.40:11434 with your Ollama server’s real address (never localhost — from inside the container that points at the container itself), and set INFERENCE_TEXT_MODEL / INFERENCE_IMAGE_MODEL to models you have actually pulled. Pick your own account email in the UI. If a value looks specific to one machine, it’s a placeholder to change, not a literal to copy.
  • INFERENCE_TEXT_MODEL is not optional for Ollama. Its default is a GPT model name; leave it unset and Karakeep tries to reach OpenAI and fails. Always set it to your local model.
  • The plain-output setting is the make-or-break. Strict structured/JSON-schema output makes many small local models hang or return malformed data. Set INFERENCE_OUTPUT_SCHEMA=plain (older releases: the deprecated INFERENCE_SUPPORTS_STRUCTURED_OUTPUT=false). This alone is the difference between tagging that works in seconds and jobs that stall for minutes.
  • Raise INFERENCE_JOB_TIMEOUT_SEC. The 30-second default kills slow-but-valid CPU jobs. Give it room (600 is generous).
  • Node / native-module gotcha (only if you manage Node yourself): Karakeep’s better-sqlite3 is a compiled native module and a too-new Node release can crash-loop it; pin a current LTS. If you rebuild it, verify the compiled .node artifact actually changed — npm rebuild can silently no-op under npm’s install-script gate. Prove the rebuild by the artifact, not the exit code.
  • The script is also the updater. Re-run karakeep-linux.sh later to update in place.
  • Pair it with ArchiveBox for link-rot insurance: archivebox config --set SAVE_ARCHIVE_DOT_ORG=False then archivebox add --depth=0 < urls.txt. It’s batch-only (no daemon), so there’s nothing extra to monitor.
All playbooks