Admin Guide

Executive summary

Conduit is a local-first system you operate on your own machine. "Admin" means keeping the daemon, runtimes, and databases healthy; managing storage growth; upgrading safely; and ensuring MCP stays available to AI clients. If you just want the fast path, start with /docs/quickstart and keep /docs/troubleshooting handy.

What you're operating (mental model)

Conduit is a CLI plus a long-running daemon. The daemon stores state in ~/.conduit/ and listens on a local socket (~/.conduit/conduit.sock). Retrieval uses SQLite + FTS5 for keyword search, Qdrant for vector search, and optional FalkorDB for multi-hop graph traversal. AI clients call the MCP server (conduit mcp kb) to fetch minimal context with citations.

References:

• Core engine HLD: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/blob/main/docs/HLD/HLD-V0-Core-Engine.md
• MCP server design: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/blob/main/docs/MCP_SERVER_DESIGN.md
• KAG HLD: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/blob/main/docs/KAG_HLD.md

System requirements you should confirm

• OS: macOS or Linux (daemon service uses launchd on macOS and systemd user services on Linux).
• Container runtime: Podman 4.0+ (preferred, rootless) or Docker 20.10+ (supported).
• Qdrant container for vector search (required for semantic RAG).
• FalkorDB container for graph traversal (optional, only for KAG multi-hop).
• Ollama for embeddings and KAG extraction (required for semantic and KAG workflows).
• Build-only (if compiling from source): Go 1.21+, SQLite 3.35+, GCC (CGO).

First-time operator checklist (10 minutes)

1. Verify dependencies and runtimes:

conduit deps status
conduit qdrant status
conduit falkordb status
conduit ollama status

2. Run health checks:

conduit status
conduit doctor
conduit service status

3. Confirm KB sync works:

conduit kb add ~/Documents/my-project --name "My Project Docs"
conduit kb sync
conduit kb stats

4. Confirm MCP is ready:

conduit mcp status
conduit mcp configure
conduit client list

5. Validate a tool call in at least one client (see /docs/mcp).

Links: /docs/install, /docs/quickstart, /docs/mcp

Day-2 operations (keep it healthy)

Logs and diagnostics

• Logs live at ~/.conduit/logs/ or ~/Library/Logs/conduit/.
• Quick health: conduit status and conduit doctor.
• MCP logs: conduit mcp logs.
• Connector logs: conduit logs <instance-id>.
• Deep debug (advanced): run the daemon in the foreground with conduit-daemon --foreground --log-level=debug (paths vary by install).

If you need a support bundle, capture:

• conduit status --json
• conduit doctor
• conduit kb stats
• conduit mcp status
• Relevant logs from ~/.conduit/logs/

Storage growth and cleanup

What grows over time:

• ~/.conduit/conduit.db (SQLite state + FTS indexes)
• Qdrant vectors (semantic search)
• FalkorDB graph (KAG)
• Logs and client backups under ~/.conduit/

Safe cleanup actions:

• Remove a source: conduit kb remove <source-id>
• Rebuild vectors: conduit kb sync --rebuild-vectors
• Purge vectors (destructive): conduit qdrant purge (re-sync required)

Before destructive actions, take a backup:

conduit backup --output /path/to/conduit-backup.tar.gz

Updates and versioning

• Check version: conduit --version
• Source builds: follow the upgrade steps in the Admin Guide (git pull, make build, restart daemon).
• Install-script users: refer to Releases and the README for the latest installer guidance.

Admin guide: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/blob/main/docs/ADMIN_GUIDE.md Releases: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/releases/latest

Database operations (Qdrant + FalkorDB)

Health checks:

conduit qdrant status
conduit falkordb status
conduit status

Healthy signals:

• conduit status shows Qdrant running with non-zero vectors.
• conduit falkordb status reports running when KAG multi-hop is needed.

If a DB is unreachable:

conduit qdrant stop
conduit qdrant start
conduit kb sync --rebuild-vectors
 
conduit falkordb stop
conduit falkordb start

Security posture (operator view)

• Podman is preferred for rootless isolation; Docker is supported.
• If using cloud providers for KAG extraction, use environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY) rather than hardcoding secrets.
• Conduit enforces least privilege for connectors and MCP tools; the policy engine blocks sensitive paths by default.

Admin command reference (high signal, not exhaustive)

For the full command suite, see the upstream CLI index: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/blob/main/docs/CLI_COMMAND_INDEX.md

Common admin pitfalls (from real known issues)

Known issues: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/blob/main/docs/KNOWN_ISSUES.md More help: /docs/troubleshooting

When to enable KAG (operator decision)

Enable KAG only when you need multi-hop, entity-centric, auditable reasoning. It is slower and heavier than RAG, and it adds graph database dependencies. If you do enable it, ensure FalkorDB is healthy and schedule graph builds intentionally. See /docs/kag.

Getting help / filing issues

Open an issue in the Conduit utility repo: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/issues

Include:

• OS and version
• Conduit version (conduit --version)
• Commands run and exact errors
• Logs from ~/.conduit/logs/ or ~/Library/Logs/conduit/
• Steps to reproduce and expected vs actual behavior