DOCSEARCHbyAlgolia
Submit Docs

Karakeep Documentation

website·Indexed 35 days ago

https://docs.karakeep.app

Documentation for Karakeep v0.33.0, a self-hostable bookmarking and read-it-later service. Includes guides on installation via Docker, Kubernetes, PikaPods, and Linux; API references for managing bookmarks, tags, and highlights; and configuration for AI providers, environment variables, and Model Context Protocol (MCP) integrations.

Tokens
24.5K
Snippets
170
Records
253
Agent score
70%

What's inside Karakeep

  1. Understand the KaraKeep system architecture

    KaraKeep is built using a NextJS web application that utilizes SQLite for data storage. The system employs a worker-based architecture to process asynchronous tasks from a SQLite-based job queue. There are three primary worker job types:

    1. Crawling: Uses a headless Chrome browser within the worker container to fetch content from links.
    2. OpenAI: Integrates with OpenAI APIs to automatically infer tags for the fetched content.
    3. Indexing: Syncs content into Meilisearch to enable high-performance search and retrieval.

  2. Karakeep core features and capabilities

    Karakeep is an open-source "Bookmark Everything" application designed for self-hosting. Key capabilities include:

    • AI-Powered Organization: Automatic tagging and summarization using LLMs (including support for local models via Ollama).
    • Content Extraction: Automatic fetching of link titles, descriptions, and images, as well as OCR for text extraction from images.
    • Search & Retrieval: Full-text and semantic search across all stored content.
    • Archiving: Full page archival using monolith to prevent link rot and automatic video archiving via yt-dlp.
    • Management: Rule-based engine for customized management, bulk actions, and the ability to sort bookmarks into collaborative lists.
    • Data Import: Importers for Chrome, Pocket, Linkwarden, Omnivore, and Tab Session Manager; automatic sync with browser bookmarks via Floccus.
    • Integration: REST API, CLI for LLM Agents (e.g., OpenClaw, Hermes), and RSS feed auto-hoarding.

  3. Automate bookmark organization with the Karakeep Rule Engine

    The Karakeep Rule Engine allows users to create 'if-this-then-that' style automation rules. These rules can automatically tag, favorite, or route bookmarks into specific lists based on the bookmark's metadata or content. Common use cases include auto-archiving newsletters, auto-tagging specific domains, or flagging video content to keep inboxes organized.

  4. Retrieve a single tag by ID

    Use the GET /tags/:tagId endpoint to retrieve detailed information about a specific tag, including the number of bookmarks associated with it. This endpoint is available in version v0.33.0.
    curl -X GET "https://<your-instance>/tags/{tagId}"

  5. Understand the Karakeep project directory structure

    The Karakeep project (v0.33.0) is organized as a monorepo. The primary applications are located in the apps/ directory, shared business logic and database schemas are in packages/, and development configurations are in tooling/.

  6. Import bookmarks from Pocket to Karakeep

    To import bookmarks from Pocket: 1. Visit the Pocket export page (https://getpocket.com/export) and request an export. 2. Pocket will email a zip file containing a CSV file of your bookmarks. 3. Unzip the file to extract the CSV. 4. In Karakeep settings, click 'Import Bookmarks from Pocket export' and upload the CSV file.

  7. Manage and apply database schema migrations

    The database schema is defined in packages/db/schema.ts. Any changes to this schema require a migration to be generated and applied to the database.
    # 1. Generate the migration with a descriptive name
pnpm run db:generate --name description_of_schema_change

# 2. Apply the migration to the database
pnpm run db:migrate

  8. Update Karakeep Docker installation

    The update method depends on how the KARAKEEP_VERSION environment variable is configured:

    1. Pinned Version: If you specified a version (e.g., 0.10.0), update the version number in the .env file and run docker compose up -d.
    2. Release Tag: If using KARAKEEP_VERSION=release, force Docker to pull the latest image by running the command with the --pull always flag.
    # For KARAKEEP_VERSION=release
docker compose up --pull always -d

  9. Start Karakeep development environment using the automated script

    The fastest way to start development is using the start-dev.sh script. This script automates the startup of Meilisearch and headless Chrome in Docker, installs dependencies via pnpm, and launches the web app and workers in parallel. Stop all services and clean up Docker containers by pressing Ctrl+C.
    ./start-dev.sh

  10. Create dynamic views with Smart lists in Karakeep

    Smart lists are auto-updating collections powered by saved search queries. They are used to create dynamic views of saved items based on specific criteria. Examples include filtering for specific tags (e.g., #ai -archived), timeframes (e.g., 'Youtube links added last week'), or specific sources (e.g., 'All reddit links from r/selfhosted').

  11. Authenticate requests to the Karakeep API

    All Karakeep API endpoints require a Bearer token passed in the Authorization header. The token format is JWT. You can generate an API key from the Karakeep web UI by navigating to Settings > API Keys.
    Authorization: Bearer <YOUR_JWT_TOKEN>

  12. Configure embedding and vector store settings

    Use these environment variables to control how Karakeep handles embedding generation and vector indexing. Ensure EMBEDDING_DIMENSIONS matches the specific requirements of your chosen embedding model or provider.
    # The embedding vector dimensions (must match your model/provider)
EMBEDDING_DIMENSIONS=1536

# Number of concurrent workers for embedding and indexing
EMBEDDING_NUM_WORKERS=1

# Timeout in seconds for embedding/indexing jobs
EMBEDDING_JOB_TIMEOUT_SEC=60