Getting Started (Local Setup)

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• services/memory-api/README.md
• services/memory-api/src/config.ts
• scripts/build-publish.sh
• CONTRIBUTING.md
• services/memory-api/package.json

Nyansa is a self-hosted AI "second brain" that runs a stack of local LLMs, a vector store, and a workflow engine on private infrastructure. The local setup allows developers to experiment with private AI solutions by connecting an Obsidian vault to local inference models and automated workflows. Sources: README.md:10-14, CONTRIBUTING.md:12-17

This guide details the prerequisites, configuration, and execution steps required to launch the Nyansa stack on a local machine using Docker Compose. Sources: README.md:154-159

System Architecture

The local stack operates within a dedicated internal Docker network named nyansa. It uses named volumes for data persistence and binds the host's Obsidian vault folder to the n8n and memory-api services. Sources: README.md:18-20, README.md:47-66

The following diagram illustrates the internal service communication and data flow during local operation:

Prerequisites

Before starting the setup, ensure your environment meets these requirements:

• Docker: Docker Compose v2.24 or later. Sources: README.md:156-157
• Hardware: A machine capable of running local LLMs. Nyansa supports cpu, gpu-nvidia, and gpu-amd profiles. Sources: README.md:21-25
• Obsidian Vault: An existing directory containing Markdown notes. Sources: README.md:158-159

Initial Configuration

You must configure environment variables to secure the services and define data paths.

1. Clone the repository and prepare the environment file:

   git clone https://github.com/Geobatpo07/nyansa.git
   cd nyansa
   cp .env.example .env
   

   Sources: README.md:163-167

2. Generate 32-character hex secrets for all security variables using openssl rand -hex 32. Sources: README.md:185-186

Required Environment Variables

Variable	Description	Source
POSTGRES_PASSWORD	Password for the PostgreSQL state database.	README.md:173
QDRANT_API_KEY	API key required to access the vector store.	README.md:177, config.ts:13
MEMORY_API_TOKEN	Bearer token for the RAG service (min 32 chars).	README.md:178, config.ts:8
OBSIDIAN_VAULT_PATH	The absolute path to your Obsidian vault on the host.	README.md:180, config.ts:9
WEBUI_ADMIN_EMAIL	Email for the initial Open WebUI admin account.	README.md:179
N8N_ENCRYPTION_KEY	Key for encrypting credentials within n8n.	README.md:174

Execution and Initial Ingestion

Start the stack using the profile that matches your hardware. The first run triggers a model download of qwen2.5:3b and nomic-embed-text. Sources: README.md:21-23, README.md:193-194

# Start the stack for CPU-only machines
docker compose --profile cpu up -d --build

# Monitor the model download progress
docker logs -f nyansa-ollama-pull-model

Sources: README.md:193-195

Manual Ingestion Trigger

After the containers are healthy, you must trigger the memory-api to index the Obsidian vault. Because the service is internal, use docker exec to route the request through a container on the nyansa network. Sources: README.md:197-200

# Set the token from your .env
TOKEN=<MEMORY_API_TOKEN>

# Trigger full vault ingestion
docker exec nyansa-open-webui curl -s -X POST http://nyansa-memory-api:8080/ingest \
  -H "authorization: Bearer $TOKEN"

Sources: README.md:201-203

Service Access

Once the stack is running, access the user interfaces via the following local URLs:

• Open WebUI: http://localhost:3000 — Used for chatting with the LLM. Sources: README.md:211
• n8n Editor: http://localhost:5678 — Used for building and managing AI workflows. Sources: README.md:212

Internal services like Qdrant and Ollama do not publish ports to the host by default for security. Sources: README.md:83-84

Development and Testing

If you are modifying the memory-api service, you can run tests and typechecks locally. The service requires Node.js 24 or later. Sources: package.json:9-11

cd services/memory-api
npm ci
npm test            # Runs Vitest suites
npm run typecheck   # Runs TypeScript validation

Sources: README.md:221-222, package.json:14-18

Build Validation

To verify the integrity of the project structure and check for secret exposure before deployment:

# Check port exposure for all profile combinations
scripts/check-exposure.sh --env-file .env.example

# Scan for tracked secrets
scripts/check-secrets.sh HEAD

Sources: README.md:223-225

Local setup provides a private environment where notes are processed into vectors and stored in Qdrant, enabling semantic search and AI assistance without sending data to external providers. Sources: README.md:10-14, CONTRIBUTING.md:26-29