Typesense

typesense — Installable Typo-Tolerant Search Environment

Typesense is a fast, typo-tolerant open-source search engine — an Algolia alternative and an easier-to-use ElasticSearch alternative. It is a single C++ binary with no runtime dependencies, architected for low-latency (<50ms) instant search. This skill is the routing-first wrapper: choose how to run the server, wire a client, model the data, and drive search + UI + production hardening.

When to use this skill

• The user wants to stand up a search backend for a site, app, catalog,

docs, or product browsing experience

• The user asks to install/run Typesense (binary, Docker, or Typesense Cloud)
• The user wants **typo tolerance, faceting/filtering, geo-search, sorting,

grouping, synonyms, curation, scoped API keys, or federated multi-search**

• The user wants to migrate off Algolia or Elasticsearch to a self-hosted

or managed open-source engine

• The user wants an InstantSearch.js UI or a Raft HA cluster in front

of / around Typesense

When not to use this skill

• The user wants LLM trace/eval observability (hallucination, prompt

scoring) → use opik / langsmith

• The user wants token-efficient code search for agents over a repo →

use semble

• The user wants generic service dashboards / uptime alerts (non-search

telemetry) → use monitoring-observability

• The user wants a vector database purpose-built for embeddings only —

Typesense does vector + hybrid search, but a dedicated store may fit better for pure ANN at extreme scale; confirm the workload first

Prerequisites

Instructions

Step 1 — Choose the server mode

Local Docker server (pin a real version tag, set a strong key):

docker run -p 8108:8108 -v /tmp/typesense-data:/data \
  typesense/typesense:27.1 --data-dir /data --api-key=CHANGE_ME_STRONG_KEY

The skill ships `scripts/install.sh` to start a local Docker server and install the Python client in one shot.

Step 2 — Install an API client

pip install typesense        # Python (official)
npm install typesense        # JS/TS (official)
# PHP: composer require typesense/typesense-php   Ruby: gem install typesense

Prefer an official client over raw CURL — they ship a smart retry strategy for HA setups. See `references/commands.md` for the full client + integration matrix.

Step 3 — Design the collection schema

A collection is an index with a typed schema. Mark fields facet: true to filter/drill-down, and set default_sorting_field for ranking:

import typesense
client = typesense.Client({
    "api_key": "CHANGE_ME_STRONG_KEY",
    "nodes": [{"host": "localhost", "port": "8108", "protocol": "http"}],
    "connection_timeout_seconds": 2,
})
client.collections.create({
    "name": "companies",
    "fields": [
        {"name": "company_name", "type": "string"},
        {"name": "num_employees", "type": "int32"},
        {"name": "country", "type": "string", "facet": True},
    ],
    "default_sorting_field": "num_employees",
})

Unlike Algolia, most settings (searchable fields, facets, ranking) are set at query time, so one collection serves many sort orders — less memory, more flexibility.

Step 4 — Index documents

client.collections["companies"].documents.create({
    "id": "124", "company_name": "Stark Industries",
    "num_employees": 5215, "country": "USA",
})
# Bulk import (JSONL) for large datasets:
# client.collections["companies"].documents.import_(jsonl_lines, {"action": "upsert"})

Step 5 — Search (typo tolerance + facets + filters + geo)

client.collections["companies"].documents.search({
    "q": "stork",                       # typo of "stark" — handled out of the box
    "query_by": "company_name",
    "filter_by": "num_employees:>100",
    "sort_by": "num_employees:desc",
    "facet_by": "country",
})

Capabilities to reach for: faceting/filtering, geo-search (sort by distance), grouping & distinct, synonyms, curation/merchandizing (pin records), federated multi-search across collections in one request, and vector / hybrid search. Details in `references/commands.md`.

Step 6 — Search UI + production

• UI: the InstantSearch.js adapter

gives filtering, sorting, pagination, and as-you-type UI fast.

• Multi-tenant: generate scoped API keys that restrict access to

certain records — never ship the admin key to the client.

• HA: run a Raft-based cluster (typically 3 nodes) for high

availability; upgrades are a binary swap + restart.

Step 7 — Plugin-style installation alongside jeo-skills

This skill folder is plugin-installable through the standard jeo-skills flow so the wrapper, references, and installer land on disk for any supported agent runtime:

# Project install (writes into .agents/skills/typesense/)
npx skills add https://github.com/akillness/jeo-skills --skill typesense

# Global install for every detected agent
npx skills add -g https://github.com/akillness/jeo-skills --skill typesense

# Target specific agents
npx skills add -g https://github.com/akillness/jeo-skills --skill typesense -a claude-code -a codex -y

Output format

When the user asks typesense for help, return a compact brief:

# typesense Routing Brief

## Scope
- Server mode: docker | binary | cloud | undecided
- Client: python | js | php | ruby | community
- Stage: install-server | install-client | schema-design | index | search | ui | production-ha

## Recommended next move
- start-docker-server | install-client | create-collection | import-docs | run-search | wire-instantsearch | scoped-keys | cluster

## Why
- 2-3 bullets grounded in the user's packet

## Route-outs
- `opik` / `langsmith` for LLM trace/eval observability
- `semble` for agent-facing code search over a repo
- `monitoring-observability` for non-search service telemetry

Best practices

1. Pin a version tag, never `latest` — typesense/typesense:27.1, and keep the data dir on a real volume so restarts don't lose the index. 2. Set settings at query time — searchable fields, facets, sort, and ranking are per-query; you rarely need multiple collections for sort orders. 3. Mark facets in the schema — facet: true is required for filtering / drill-down on a field. 4. Use scoped API keys for clients — the admin key stays server-side; scoped keys enforce per-tenant record access. 5. Bulk import as JSONL with `upsert` — far faster than per-document creates for large datasets; size RAM to the index (memory-resident). 6. License awareness — the server is GPL, the client libraries are Apache-2.0; run the server as a separate daemon (the intended use).

References

• Upstream repo: <https://github.com/typesense/typesense>
• API docs: <https://typesense.org/api>
• Guide / walk-through: <https://typesense.org/guide>
• Downloads (binary): <https://typesense.org/downloads>
• Docker image: <https://hub.docker.com/r/typesense/typesense>
• Typesense Cloud: <https://cloud.typesense.org>
• InstantSearch adapter: <https://github.com/typesense/typesense-instantsearch-adapter>
• Installer script: `scripts/install.sh`
• Client + integration matrix: `references/commands.md`
• Adjacent skills: ../opik/SKILL.md, ../semble/SKILL.md,

../monitoring-observability/SKILL.md

• License: GPL-3.0 (server); API clients Apache-2.0

typesense command + client reference

Upstream: <https://github.com/typesense/typesense> · API docs: <https://typesense.org/api>

Server (run modes)

Build from source (Docker): TYPESENSE_VERSION=nightly ./docker-build.sh --build-deploy-image --create-binary.

API clients

Official clients ship a smart retry strategy for HA; prefer them over raw CURL.

Core API surface

Search parameters (selected)

Feature map

Typo tolerance · faceting & filtering · sorting (query-time) · grouping & distinct · federated multi-search · geo search · vector + hybrid search · scoped API keys (multi-tenant) · synonyms · curation / merchandizing (pinned hits) · Raft-based clustering (HA) · seamless version upgrades (binary swap) · no runtime dependencies.

Search UI

InstantSearch.js adapter: <https://github.com/typesense/typesense-instantsearch-adapter> — filtering, sorting, pagination, as-you-type UI on top of Typesense.

Operations notes

• Memory-resident index: size RAM to the dataset (rough: 1M HN titles ≈

165 MB). A fresh server ≈ 30 MB.

• HA: 3-node Raft cluster typical; upgrades swap the binary + restart.
• Licensing: server is GPL-3.0; client libraries are Apache-2.0 — run the

server as a standalone daemon (intended use).