GUI Companion (Experimental)

Executive summary

The GUI is an experimental macOS companion to the Conduit CLI. It exists to make the most common workflows easier (KB sources, sync, basic queries, status), but it is not a full replacement. If you hit sharp edges, use the CLI as the reliable path. Start with /docs/cli and /docs/quickstart.

Image

conduit-gui-macos-screenshot | alt: Screenshot of the Conduit macOS GUI showing KB sources, sync status, and quick actions (built on top of the CLI).

What the GUI is (and what it is not)

The GUI is built on top of the CLI. The CLI and daemon remain the source of truth; the GUI is a cockpit.

From the GUI HLD:

The GUI never directly edits client configs.
The GUI never runs containers.
The GUI never stores secrets.
The GUI calls CLI -> CLI calls daemon -> daemon performs actions.

Who should use this

macOS users who want visibility into status and quick KB actions.
Teams trying Conduit for the first time and preferring a visual cockpit.

Who should stick to the CLI

Anyone needing full feature coverage and advanced flags.
Large runs, automation, or CI workflows.
Debugging and admin operations.

What you can do today (capabilities)

Based on the GUI HLD and README, the experimental GUI includes:

Dashboard with real-time status.
Knowledge Base management (sources, sync, search) and RAG tuning.
KAG search interface (experimental).
Connector instance view (list, start, stop).
Settings and configuration view.
Setup wizard for first-run onboarding.

Coverage depends on the current GUI build. Refer to the Desktop App Details in the Conduit repo and the Releases page for the latest scope:

Known limitations

Experimental and under active development; bugs are expected.
Current releases are macOS Apple Silicon DMGs. Cross-platform support is a stated goal, but other binaries are not documented in Releases.
Feature parity with the CLI is incomplete; CLI remains the reliable path.
Containerized dependencies (Qdrant, FalkorDB) still need to be healthy; troubleshooting often falls back to CLI.

Install / run the GUI (point to source of truth)

Prereqs (verified)

macOS (current releases are Apple Silicon DMG builds).
Conduit is CLI-first; the GUI relies on the daemon and local services. Follow /docs/install if you have not set up Conduit.

How to get it

Download the DMG from Releases: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/releases/latest
Apple Silicon DMG pattern: Conduit-x.x.x-arm64.dmg

macOS security note (from the README): If you see "Conduit.app is damaged", run:

xattr -cr /Applications/Conduit.app

If you need more detail, follow the Desktop App section in the Conduit repo:

How the GUI maps to the CLI (mental model)

The GUI is a thin layer on top of the CLI and daemon. The CLI owns configuration and state, and the GUI calls CLI commands under the hood. If something works in the CLI but not in the GUI, it is likely a GUI surface gap, not a core capability issue.

Recommended pattern: get it working in CLI first (see /docs/quickstart), then use the GUI for convenience.

When to drop to CLI

Advanced flags and tuning.
Large runs or automation.
Debugging and log collection.
Admin operations (service management, backups, data repair).

Troubleshooting

Symptom	Likely cause	What to do next
GUI shows no KB results	KB not synced or semantic index missing	Run `conduit kb sync` and verify `conduit status`. If vectors are missing, run `conduit kb sync --rebuild-vectors`.
GUI shows degraded semantic search	Qdrant unavailable or 0 vectors	Run `conduit doctor`, then `conduit qdrant stop` and `conduit qdrant start`, then re-sync.
KAG actions are empty	KAG not enabled or not synced	Ensure `kag.enabled: true` in config, run `conduit kb kag-sync`, and check `conduit kb kag-status`.
Graph traversal missing	FalkorDB not running	Run `conduit falkordb status`, then restart if needed.
GUI status seems stale	Daemon not running or not responding	Run `conduit status` and `conduit service start` if needed.

For more, see /docs/troubleshooting and the Known Issues doc: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/blob/main/docs/KNOWN_ISSUES.md

Feedback + contributions

The GUI is open source and evolving quickly. Feedback is welcome.

File issues: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/issues
Include: macOS version, Conduit version, steps to reproduce, logs (~/.conduit/logs/), and screenshots.
Small PRs are welcome: docs fixes, UI polish, and bug fixes.