User Guide

Everything you need to install, configure, and build with Montycat — from getting started to governance, advanced operations, and security.

Installation

Editions: Montycat & Montycat Semantic

Montycat ships in two editions:

  • Montycat Semantic — the full engine plus built-in AI semantic (vector) search: on-device embeddings and an HNSW vector index, enabled by default. No external embedding services, no separate vector database. Pick this one for RAG, AI agents, and LLM memory.
  • Montycat — the lean core engine: persistent + in-memory keyspaces, subscriptions, snapshots, the full NoSQL data mesh, without the embedding runtime. Smallest footprint.

The edition is selected at install time — a Docker tag (semantic instead of latest) or the apt package name (montycat-semantic instead of montycat). Client libraries and the API are identical for both.

Most portable & flexible option. Run Montycat in a container to isolate it from your system.

  • Pull an official image from DockerHub or use docker-compose .yml / .yaml file for deployment.
  • Define environmental variables for configuration.
  • Create your own custom container using a Dockerfile for advanced setups.

Install Montycat Semantic (AI / RAG)

Recommended for AI, RAG, and agent memory. Semantic search is enabled by default — no external embedding service, no separate vector database, nothing to wire up. Use the Docker tag semantic or the apt package montycat-semantic.

# Montycat Semantic — built-in AI vector search, enabled by default.
FROM montygovernance/montycat:semantic
# Hardened (distroless, minimal attack surface): montygovernance/montycat:semantic-hardened
# Apple Silicon / ARM64:  montygovernance/montycat:arm64-semantic
#                         montygovernance/montycat:arm64-semantic-hardened

# MONTYCAT_SNAPSHOT_RATE default is 0 seconds (snapshot disabled)
# MONTYCAT_EXPIRATION_RATE default is 1 second
# MONTYCAT_REPORTS_ALLOWED default is true so it can be overridden with MONTYCAT_REPORTS_ALLOWED=false
# MONTYCAT_SUPEROWNER and MONTYCAT_PASSWORD will setup on container startup then safely returns false

ENV MONTYCAT_SNAPSHOT_RATE=60
ENV MONTYCAT_SUPEROWNER=superowner
ENV MONTYCAT_PASSWORD=password
ENV MONTYCAT_EXPIRATION_RATE=10
ENV MONTYCAT_REPORTS_ALLOWED=true

Install Montycat (base)

The lean core engine, without the embedding runtime — the smallest image. Use the Docker tag latest or the apt package montycat.

FROM montygovernance/montycat:latest
# Hardened (distroless, minimal attack surface): montygovernance/montycat:hardened
# Apple Silicon / ARM64: montygovernance/montycat:arm64 (or arm64-hardened)
# Need AI semantic search? Use the Montycat Semantic edition (section above).

# MONTYCAT_SNAPSHOT_RATE default is 0 seconds (snapshot disabled)
# MONTYCAT_EXPIRATION_RATE default is 1 second
# MONTYCAT_REPORTS_ALLOWED default is true so it can be overridden with MONTYCAT_REPORTS_ALLOWED=false
# MONTYCAT_SUPEROWNER and MONTYCAT_PASSWORD will setup on container startup then safely returns false

ENV MONTYCAT_SNAPSHOT_RATE=60
ENV MONTYCAT_SUPEROWNER=superowner
ENV MONTYCAT_PASSWORD=password
ENV MONTYCAT_EXPIRATION_RATE=10
ENV MONTYCAT_REPORTS_ALLOWED=true

Hardened images

Every edition also ships a hardened Docker image built on distroless bases (distroless/static-debian12 for base, distroless/base-debian13 for semantic). They contain no shell and no package manager, for a reduced production attack surface — the same engine, a smaller image.
Tags: hardened and semantic-hardened (plus the ARM64 variants arm64-hardened and arm64-semantic-hardened). Because there is no shell, debug with docker logs rather than docker exec.

ARM64 / Apple Silicon

The default (unprefixed) tags — latest, hardened, semantic, semantic-hardened — are linux/amd64. For ARM64 / Apple Silicon, use the arm64-prefixed equivalents: arm64, arm64-hardened, arm64-semantic, and arm64-semantic-hardened.
The apt repository is amd64 only — on ARM64 hosts run the ARM64 Docker image instead.