Referenced Files in This Document

• README.md
• compose.yaml
• Dockerfile
• package.json
• src/index.ts
• src/server.ts
• src/bootstrap.ts
• src/config.ts
• src/http/http-server-startup.ts
• src/cli/program.ts
• src/cli/commands/serve.ts
• src/cli/commands/login.ts
• src/cli/commands/token.ts
• src/cli/commands/search.ts
• src/cli/commands/spaces.ts
• src/cli/commands/export.ts
• src/cli/commands/train.ts
• src/cli/commands/update.ts
• src/cli/config-file.ts
• src/cli/config.ts
• src/cli/api-client.ts
• src/cli/resolve-api-base.ts
• src/cli/safe-http-url.ts
• src/cli/oauth-refresh.ts
• src/cli/auth-error.ts
• src/cli/keyring.ts
• src/services/redis.ts
• src/services/qdrant/service.ts
• src/services/embedding/service.ts
• src/utils/global-error-handlers.ts
• scripts/env/create-env.sh
• scripts/ci-wait-for-infra.sh
• docs/install/prerequisites.md
• docs/install/docker-compose-simple.md
• docs/install/docker-compose-full-stack.md
• docs/CLI.md

Changes Made

• Updated documentation structure to reflect migration from manual 'Started.md' file to automated .qoder/repowiki documentation system
• Consolidated getting started content into the automated wiki structure
• Maintained all existing installation and setup instructions while improving organization
• Enhanced cross-references to align with new documentation architecture

1. Introduction
2. Prerequisites
3. Quick Start with Docker Compose
4. Local Development with npm
5. Basic Configuration
6. Start the Server and Access the Web Interface
7. Run Your First CLI Command
8. Troubleshooting Common Issues
9. Next Steps

This guide helps you install, configure, and run Kairos MCP quickly using Docker Compose or npm. You will start the server, open the web interface, and execute your first CLI commands to interact with the system.

As part of our documentation modernization effort, this getting started content has been consolidated into the automated wiki structure for better maintainability and consistency across the project documentation.

Before installing, ensure the following are available on your machine:

• Node.js (LTS recommended)
• npm
• Docker and Docker Compose
• External services:
  • PostgreSQL
  • Redis
  • Qdrant

For detailed prerequisites and environment requirements, see:

• docs/install/prerequisites.md

Section sources

• docs/install/prerequisites.md

The repository includes a compose file that orchestrates the application and its dependencies.

Steps:

1. Clone the repository and navigate to the project root.
2. Ensure Docker is running and your user has permission to use Docker.
3. Use the provided compose file to start all services:
   • Run: docker compose up --build
4. Wait for the services to initialize. The application will be accessible at the configured HTTP port.

Notes:

• The compose file defines the main service and required infrastructure. See:
  • compose.yaml
• The container image is built from:
  • Dockerfile

After startup:

• Open the web UI at http://localhost: (use the port defined in your configuration).
• Verify health endpoints if exposed by your configuration.

Section sources

• compose.yaml
• Dockerfile

If you prefer to run the server locally without containers:

1. Install dependencies:
   • npm ci
2. Build the UI assets (if required by your setup):
   • npm run build
3. Configure environment variables as described in Basic Configuration.
4. Start the server:
   • npm start

The server entry points and bootstrap logic are implemented in:

• src/index.ts
• src/server.ts
• src/bootstrap.ts

Section sources

• package.json
• src/index.ts
• src/server.ts
• src/bootstrap.ts

Kairos MCP reads configuration from environment variables. Key areas include:

• Application server settings (host, port)
• Database connection (PostgreSQL)
• Cache/session store (Redis)
• Vector search index (Qdrant)
• Embedding provider settings
• Authentication (OIDC) and UI base URL

Configuration loading and defaults are handled in:

• src/config.ts

Service integrations:

• Redis client initialization: src/services/redis.ts
• Qdrant service initialization: src/services/qdrant/service.ts
• Embedding service initialization: src/services/embedding/service.ts

Environment scaffolding helper:

• scripts/env/create-env.sh

Tips:

• For simple setups, follow the minimal compose example:
  • docs/install/docker-compose-simple.md
• For full stack including Keycloak and additional components:
  • docs/install/docker-compose-full-stack.md

Section sources

• src/config.ts
• src/services/redis.ts
• src/services/qdrant/service.ts
• src/services/embedding/service.ts
• scripts/env/create-env.sh
• docs/install/docker-compose-simple.md
• docs/install/docker-compose-full-stack.md

Starting the server:

• Using Docker Compose: docker compose up --build
• Using npm: npm start

HTTP server startup and routing are implemented in:

• src/http/http-server-startup.ts

Once started:

• Open the web UI at http://localhost: (replace with your configured port).
• If authentication is enabled, log in via the configured OIDC provider.

Section sources

• src/http/http-server-startup.ts

The CLI provides commands to manage sessions, spaces, exports, training, and more.

Common first steps:

• Login to authenticate:
  • kairos login
• Get or refresh an access token:
  • kairos token
• Search across your data:
  • kairos search ""
• List or manage spaces:
  • kairos spaces list
• Export artifacts:
  • kairos export ...
• Train models or datasets:
  • kairos train ...
• Update the CLI:
  • kairos update

CLI program and command implementations:

• Program entry and command registration: src/cli/program.ts
• Serve command (for local development): src/cli/commands/serve.ts
• Authentication and tokens:
  • src/cli/commands/login.ts
  • src/cli/commands/token.ts
• Core operations:
  • src/cli/commands/search.ts
  • src/cli/commands/spaces.ts
  • src/cli/commands/export.ts
  • src/cli/commands/train.ts
  • src/cli/commands/update.ts

CLI configuration and API client:

• Config file handling: src/cli/config-file.ts
• Runtime config resolution: src/cli/config.ts
• API client and base URL resolution:
  • src/cli/api-client.ts
  • src/cli/resolve-api-base.ts
  • src/cli/safe-http-url.ts
• OAuth refresh and auth error handling:
  • src/cli/oauth-refresh.ts
  • src/cli/auth-error.ts
• Secure storage helpers:
  • src/cli/keyring.ts

For a complete reference of CLI commands and options, see:

• docs/CLI.md

Section sources

• src/cli/program.ts
• src/cli/commands/serve.ts
• src/cli/commands/login.ts
• src/cli/commands/token.ts
• src/cli/commands/search.ts
• src/cli/commands/spaces.ts
• src/cli/commands/export.ts
• src/cli/commands/train.ts
• src/cli/commands/update.ts
• src/cli/config-file.ts
• src/cli/config.ts
• src/cli/api-client.ts
• src/cli/resolve-api-base.ts
• src/cli/safe-http-url.ts
• src/cli/oauth-refresh.ts
• src/cli/auth-error.ts
• src/cli/keyring.ts
• docs/CLI.md

• Cannot connect to PostgreSQL:
  • Verify host, port, credentials, and database name in environment variables.
  • Ensure the database is reachable from the application container or localhost.
• Redis connection errors:
  • Confirm Redis URL and network accessibility.
  • Check firewall rules and container networking.
• Qdrant not responding:
  • Validate Qdrant endpoint and collection readiness.
  • Review initialization logs for migration or schema issues.
• Embedding provider failures:
  • Check provider credentials and rate limits.
  • Inspect embedding service logs for errors.
• Authentication problems:
  • Ensure OIDC issuer, client ID, and redirect URLs are correct.
  • Use the CLI login flow to obtain a valid token.
• Health checks failing:
  • Use the health endpoints exposed by the HTTP server to verify readiness.

Helpful scripts and utilities:

• Environment scaffolding: scripts/env/create-env.sh
• Infrastructure wait helper (used in CI and tests): scripts/ci-wait-for-infra.sh
• Global error handlers for consistent logging: src/utils/global-error-handlers.ts

Section sources

• scripts/env/create-env.sh
• scripts/ci-wait-for-infra.sh
• src/utils/global-error-handlers.ts

• Explore advanced installation options:
  • Simple stack: docs/install/docker-compose-simple.md
  • Full stack with Keycloak: docs/install/docker-compose-full-stack.md
• Learn about architecture and components:
  • docs/architecture/README.md
• Dive into CLI usage:
  • docs/CLI.md

[No sources needed since this section summarizes without analyzing specific files]