Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tudoumono/Sherpa/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning Sherpa, starting the backing stores, registering a document folder as a knowledge base, and sending your first question. Everything runs locally on Linux or WSL2. The whole process takes about five minutes on a machine where Python 3 and Docker are already installed.

​
Prerequisites

Before you start, make sure the following are available on your machine:
RequirementCheckNotes
Python 3python3 --versionIncludes python3-venv and python3-pip
Docker Engine + Docker Composedocker --version and docker compose versionDocker Desktop works too — start the app first
On Ubuntu or WSL2, if Docker is not yet installed, run the helper script that ships with Sherpa:
make install-docker
This installs Docker Engine using the official script. You will be prompted for your sudo password once.

​
Setup and first query

1

Clone the repository

Clone the Sherpa repository and enter the project directory:
git clone <repository-url>
cd Sherpa
Alternatively, if you downloaded a release tarball from the GitHub Releases page:
tar xzf sherpa-vX.Y.Z.tar.gz
cd sherpa-vX.Y.Z
2

Start Sherpa

Run the single startup script:
./scripts/start.sh
You can also use the Makefile alias:
make start
On the first run, start.sh does the following in order:
  1. Creates a Python virtual environment at .venv/
  2. Installs all Python dependencies from requirements.txt
  3. Starts the Docker containers for PostgreSQL, Neo4j, and Elasticsearch (docker compose up -d)
  4. Runs scripts/bootstrap.sh to create required local directories and prepare the .env file
  5. Launches the FastAPI application on port 8000
If OPENAI_API_KEY in your .env is unset or still set to the placeholder sk-REPLACE_ME, the script prints an advisory message but does not block startup. You can still use the chat UI with the “No AI” or “Local LLM (Ollama)” model options.
To use a different port, prefix the command with the SHERPA_PORT variable:
SHERPA_PORT=8010 ./scripts/start.sh
The chat UI will then be at http://127.0.0.1:8010/ui/chat.html.
3

Open the chat UI

Once the terminal shows the startup URL, open your browser and navigate to:
http://127.0.0.1:8000/ui/chat.html
Without authentication enabled (the default for local use), you are automatically logged in as the admin user. No separate login step is required.
4

Register a document folder

Before you can search, you need to register a local folder as a world (Sherpa’s term for a knowledge base).
  1. In the UI, navigate to the Ingest screen (look for the folder / ingest icon in the sidebar).
  2. Enter a name for your world (e.g. my-project).
  3. Enter the absolute path to the folder on your local machine that contains the documents you want to index (e.g. /home/you/projects/my-project/docs).
  4. Click Register.
Sherpa records the folder path and assigns it a world_id. The folder itself is not copied — Sherpa reads from it in place.
Each registered folder is exactly one world: one Neo4j graph and one Elasticsearch index. If you have multiple independent projects, register each as a separate world.
5

Run the first ingest

After registering the folder, trigger the initial ingest:
  1. Select the world you just registered.
  2. Click Run ingest (or Start ingestion).
Sherpa scans the folder, converts Office/Word/Excel files to Markdown, runs static analysis on any source files (COBOL, JCL), and calls the configured AI provider to extract semantic relationships. Progress is shown in the UI. For a small folder this takes seconds; for thousands of files it may take several minutes.When ingest completes, the world status changes to Ready.
Re-ingest any time the folder contents change. Updated files are replaced, deleted files are removed, and new files are added. There is no separate “publish” step.
6

Ask your first question

Return to the Chat screen (http://127.0.0.1:8000/ui/chat.html).
  1. In the model/settings bar, make sure Knowledge retrieval (ナレッジ参照) is toggled on. This instructs Sherpa to search the knowledge base and attach citations.
  2. Select your world from the world/scope selector.
  3. Type a question in the input box, for example: 
    What is affected if we change the consumption tax rate?
  4. Press Enter (or click Send).
Sherpa selects the impact analysis lens, traverses the Neo4j graph from the relevant starting nodes, and returns a ranked list of affected components with traversal paths and citations. Each citation includes a download link to the original source file.
If Knowledge retrieval is off, Sherpa answers using the AI model’s general knowledge only — no documents are searched and no citations are attached. Toggle it on whenever you want answers grounded in your registered folders.

​
Stopping and cleaning up

To stop the FastAPI application, press Ctrl+C in the terminal where start.sh is running. To also stop the Docker stores (PostgreSQL, Neo4j, Elasticsearch): 
make stop
To stop the stores and permanently delete all data volumes (useful when you want a completely clean slate): 
make nuke
make nuke runs docker compose down -v, which removes all Docker volumes. All indexed knowledge, graph data, and PostgreSQL records are permanently deleted. Use with caution.
To check the current state of the stores at any time: 
make status
To tail the store logs: 
make logs

​
Troubleshooting

Python 3 is not installed or not on your PATH. On Ubuntu / WSL2, install it with:
sudo apt update && sudo apt install -y python3 python3-venv python3-pip
Confirm the installation:
python3 --version
Then re-run ./scripts/start.sh.
Docker Engine is not installed, or the Docker daemon is not running.On Ubuntu / WSL2, install Docker with the helper script:
make install-docker
If you are using Docker Desktop, make sure the application is open and running before executing start.sh. Confirm both Docker and Compose are available:
docker --version
docker compose version
Another process is listening on port 8000. Either stop that process, or start Sherpa on a different port:
SHERPA_PORT=8010 ./scripts/start.sh
Then open the UI at http://127.0.0.1:8010/ui/chat.html instead.
The Docker stores (PostgreSQL, Neo4j, or Elasticsearch) are still starting up, or Docker is not running. On first run, Docker needs to pull the container images, which can take a few minutes depending on your internet connection.Check the container status:
make status
Stream the container logs to see what is happening:
make logs
If Docker is not running at all, start Docker Desktop or the Docker daemon, then re-run ./scripts/start.sh.
The most likely cause is that OPENAI_API_KEY is not configured. Open .env (copy from .env.example if it does not exist yet) and set a real key:
# .env
OPENAI_API_KEY=sk-...your-actual-key-here...
Save the file and restart Sherpa with ./scripts/start.sh.If you do not have an OpenAI key, you can still explore the UI:
  • Select “No AI” (簡易) in the model picker to see search results without an AI summary.
  • Select “Local LLM (Ollama)” if you have Ollama running locally (set OLLAMA_URL in .env).
To get answers grounded in your registered documents, make sure the Knowledge retrieval (ナレッジ参照) toggle is turned on in the chat interface.

Build docs developers (and LLMs) love

Get started for freeTalk to us