-
Notifications
You must be signed in to change notification settings - Fork 0
Getting Started
Changes Made
- Enhanced guided setup section with detailed kairos-install skill workflow
- Expanded environment configuration section with practical examples
- Added comprehensive troubleshooting guide with specific error scenarios
- Updated deployment scenarios with concrete configuration examples
- Improved health check verification with multiple validation methods
- Enhanced initial server access section with practical verification steps
- Introduction
- Prerequisites and System Requirements
- Installation Methods
- Quick Start Guides
- Environment Configuration
- Health Check Verification
- Initial Server Access
- Deployment Scenarios
- Troubleshooting Guide
- Conclusion
KAIROS MCP is a TypeScript service that provides persistent memory and deterministic execution for AI agent workflows. It exposes:
- an MCP endpoint at POST /mcp
- REST endpoints under /api/*
- a browser UI under /ui
- a CLI named kairos
The system centers around three core ideas: persistent memory, deterministic execution (activate → forward → reward), and agent-facing design. This guide helps you install, configure, and verify KAIROS across development, production, and fullstack profiles.
Before installing KAIROS, confirm the following prerequisites:
- Node.js 24 or later (primary interface for authentication, bulk management, and verification)
- Docker Engine + Docker Compose v2 (for Docker Compose paths)
- Kubernetes 1.28+ with Helm 3.14+ and kubectl (for Helm chart path)
- Python 3 (for repository helper scripts or advanced operator workflows)
- A supported embedding backend (OpenAI, Ollama, or TEI)
Choose an embedding backend before creating your environment file. The application requires a text-embedding service to convert text into vectors for Qdrant.
Section sources
- docs/install/prerequisites.md:11-44
- docs/install/prerequisites.md:48-87
There are two primary installation paths:
- Docker Compose (recommended for local development or single-host deployments)
- Helm chart (recommended for Kubernetes clusters)
- Simple stack: Application + Qdrant (default profile)
- Full stack: Adds supporting services (Valkey/Redis, Postgres, Keycloak) via the fullstack profile
Start with the simple stack for first-time setup, then use the full stack when you need broader services.
Section sources
- docs/install/README.md:18-36
- docs/install/docker-compose-simple.md:13-42
- docs/install/docker-compose-full-stack.md:13-23
- Install operators (Qdrant, Valkey, Percona PostgreSQL, Keycloak) using the provided manifests
- Configure values files for development or production
- Deploy using Helm upgrade --install
Section sources
- docs/install/helm.md:9-33
- docs/install/helm.md:36-76
Two quick start flows are provided to get you running quickly:
Use this when you want a guided first-time setup for Ollama, .env configuration, and the minimal local stack:
- Install the setup skill using
npx skills add debian777/kairos-mcp --skill kairos-install - Ask your agent to run kairos-install for this repo
- The skill will:
- Check prerequisites (Docker, Node.js 24+, Docker Compose v2)
- Help you choose an embedding backend (OpenAI, Ollama, or TEI)
- Generate the .env file with proper configuration
- Start the Docker Compose stack
- Guide you through CLI authentication
- Verify the server with curl /health
- Open the UI or MCP endpoint
Section sources
- README.md:110-137
- skills/.system/kairos-install/SKILL.md:165-596
Use this when you want the smallest working server deployment without the guided skill:
- Create .env at the repository root with required variables
- Start the stack with docker compose -p kairos-mcp up -d
- Verify the server with curl /health
- Open the UI or MCP endpoint
Section sources
- README.md:138-167
- docs/install/docker-compose-simple.md:60-110
Environment variables drive KAIROS behavior. The minimal stack requires:
- QDRANT_API_KEY
- One embedding backend (OpenAI, Ollama, or TEI)
Ports:
- App: PORT (default 3000)
- Qdrant: 6333, 6344
- Metrics: METRICS_PORT (default 9090)
For the full stack, additional variables align with the chosen profile and secret management approach.
Section sources
- docs/install/docker-compose-simple.md:65-92
- docs/install/docker-compose-full-stack.md:36-44
- compose.yaml:139-163
After starting the stack, verify the server health:
- Use curl to hit the /health endpoint on the configured port
- For Docker Compose, the default port is 3000 unless overridden in .env
- For development scripts, the default port is often 3300
If the server does not start or returns 503, wait for Qdrant to finish starting, then retry.
Section sources
- README.md:363-371
- docs/install/docker-compose-simple.md:95-110
- scripts/deploy-run-env.sh:553-561
Once the server is healthy:
- UI: http://localhost:3000/ui
- MCP: http://localhost:3000/mcp
- Metrics: http://localhost:9090/metrics
Match the host and port used for health checks. The CLI is the primary interface for authentication, verification, and day-to-day operations.
Section sources
- README.md:133-136
- docs/install/docker-compose-simple.md:105-110
- docs/CLI.md:45-61
Choose the scenario that matches your environment:
- Recommended for local development and first-time setup
- Starts only the application and Qdrant
- Use AUTH_ENABLED=false for quick start
Section sources
- docs/install/docker-compose-simple.md:13-42
- docs/install/docker-compose-simple.md:60-110
- Use the Helm chart for Kubernetes deployments
- Configure values files for your environment
- Enable authentication and TLS as needed
Section sources
- docs/install/helm.md:36-76
- helm/values.prod.yaml:10-47
- Adds supporting services: Valkey, Postgres, Keycloak
- Use when you need a broader local environment or want to model a production-like topology
- Start with docker compose -p kairos-mcp --profile fullstack up -d
Section sources
- docs/install/docker-compose-full-stack.md:48-58
- compose.yaml:10-8
Common startup issues and resolutions:
- The server does not start: Check container logs and verify required ports are free
- Health check returns 503: Wait for Qdrant to finish starting, then retry
- Embeddings fail on startup: Set one working embedding backend in .env
- Auth-enabled development is failing: Use the fullstack env example, start the fullstack profile, and configure realms
- The CLI keeps asking for login: Confirm the API URL and token validity; validate with kairos token --validate
Additional verification steps:
- Use the CLI to check connectivity and authentication
- Confirm embedding backend health and configuration
- For Helm deployments, verify pods and routes with kubectl
Section sources
- README.md:346-401
- docs/install/docker-compose-simple.md:150-158
- scripts/deploy-run-env.sh:553-561
- docs/CLI.md:335-374
You now have the essentials to install, configure, and verify KAIROS across development, production, and fullstack profiles. Start with the simple Docker Compose path for local development, then move to the Helm chart for Kubernetes production. Use the CLI for authentication and verification, and refer to the troubleshooting section for common issues.