codebase_health
Checks infrastructure health including Docker, Qdrant, Ollama, and embedding model to diagnose setup issues.
Instructions
Check the health of all infrastructure: Docker, Qdrant container, Ollama, and embedding model. Use this to diagnose setup issues.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/index.ts:440-449 (registration)Registration of the codebase_health tool via server.tool(), delegating to handleManageTool.
// ── Management tools ───────────────────────────────────────────────────── server.tool( "codebase_health", "Check the health of all infrastructure: Docker, Qdrant container, Ollama, and embedding model. Use this to diagnose setup issues.", {}, async (args) => ({ content: [{ type: "text", text: await handleManageTool("codebase_health", args) }], }), ); - src/tools/manage-tools.ts:58-129 (handler)Handler function handleManageTool — the 'codebase_health' case checks Docker, Qdrant (external or managed), and embedding provider health, returning a human-readable status report.
export async function handleManageTool( name: string, _args: Record<string, unknown>, ): Promise<string> { switch (name) { case "codebase_health": { const config = getEmbeddingConfig(); const status: HealthStatus = { docker: false, ollama: false, qdrant: false, ollamaModel: false, qdrantImage: false, ollamaImage: false, }; const icon = (ok: boolean) => (ok ? "[OK]" : "[MISSING]"); const lines: string[] = [ "SocratiCode — Infrastructure Health Check:", "", `Qdrant mode: ${QDRANT_MODE}`, ]; if (QDRANT_MODE === "external") { const endpoint = QDRANT_URL ?? `http://${QDRANT_HOST}:${QDRANT_PORT}`; lines.push(`Qdrant endpoint: ${endpoint}`); try { await listCodebaseCollections(); status.qdrant = true; lines.push(`${icon(true)} External Qdrant (${endpoint}): Reachable`); } catch { lines.push(`${icon(false)} External Qdrant (${endpoint}): Unreachable — check QDRANT_URL / QDRANT_HOST`); } } else { // managed mode — Docker-managed container const docker = await isDockerAvailable(); status.docker = docker; lines.push(`${icon(status.docker)} Docker: ${status.docker ? "Running" : "Not found — install from https://docker.com"}`); if (docker) { const [qdrantRunning, qdrantImage] = await Promise.all([ isQdrantRunning(), isQdrantImagePresent(), ]); status.qdrant = qdrantRunning; status.qdrantImage = qdrantImage; lines.push(`${icon(status.qdrantImage)} Qdrant image: ${status.qdrantImage ? "Pulled" : "Not pulled — will be pulled on first index"}`); lines.push(`${icon(status.qdrant)} Qdrant container: ${status.qdrant ? "Running" : "Not running — will be started on first index"}`); } } // Embedding provider health check (works for ollama, openai, google) lines.push(""); lines.push(`Embedding provider: ${config.embeddingProvider}`); const provider = await getEmbeddingProvider(); const health = await provider.healthCheck(); lines.push(...health.statusLines); lines.push(""); if (QDRANT_MODE === "external") { lines.push("External Qdrant mode — Docker is not required for the vector database."); } else { lines.push( status.docker ? "Docker is available. Qdrant container will be auto-managed." : "Docker is required for Qdrant. Install from https://docker.com", ); } return lines.join("\n"); } - src/types.ts:46-53 (schema)HealthStatus interface defining boolean fields for Docker, Qdrant, Ollama, etc.
export interface HealthStatus { docker: boolean; ollama: boolean; qdrant: boolean; ollamaModel: boolean; qdrantImage: boolean; ollamaImage: boolean; } - EmbeddingHealthStatus interface returned by embedding providers' healthCheck(), used by the handler.
export interface EmbeddingHealthStatus { /** Provider is reachable and ready. */ available: boolean; /** The model/endpoint is accessible. */ modelReady: boolean; /** Human-readable status lines for the health tool. */ statusLines: string[]; } - src/services/docker.ts:41-91 (helper)Helper functions isDockerAvailable(), isQdrantImagePresent(), and isQdrantRunning() used by the health check.
export async function isDockerAvailable(): Promise<boolean> { try { await run("docker", ["info"]); return true; } catch { return false; } } // ── Qdrant ──────────────────────────────────────────────────────────────── /** Check if the Qdrant Docker image is pulled */ export async function isQdrantImagePresent(): Promise<boolean> { try { const { stdout } = await run("docker", ["images", "--format", "{{.Repository}}:{{.Tag}}", QDRANT_IMAGE]); return stdout.includes("qdrant/qdrant"); } catch { return false; } } /** Pull the Qdrant Docker image (may take several minutes on first launch) */ export async function pullQdrantImage(onProgress?: InfraProgressCallback): Promise<void> { onProgress?.("Downloading Qdrant Docker image (first time only, may take a few minutes)..."); logger.info("Pulling Qdrant Docker image", { image: QDRANT_IMAGE }); try { await run("docker", ["pull", QDRANT_IMAGE], 10 * 60_000); // 10 minute timeout for image pull } catch (error) { const msg = error instanceof Error ? error.message : String(error); if (msg.includes("timed out")) { throw new Error( `Qdrant image download timed out after 10 minutes. Check your network connection and try again.`, ); } throw new Error( `Failed to download Qdrant image. Check your network connection and available disk space.\nDetails: ${msg}`, ); } } /** Check if the Qdrant container is running */ export async function isQdrantRunning(): Promise<boolean> { try { const { stdout } = await run("docker", [ "ps", "--filter", `name=${QDRANT_CONTAINER_NAME}`, "--format", "{{.Names}}", ]); return stdout.trim().includes(QDRANT_CONTAINER_NAME); } catch { return false; } }