WeavyAdmin

WeavyAdmin is an open-source desktop GUI for administering and managing Weaviate vector database clusters to manage collections and schemas, inspect nodes and shards, run keyword/vector/hybrid searches, handle RBAC, ingest CSV data, manage backups, run diagnostics, and operate the underlying Kubernetes infrastructure (GKE/EKS). WeavyAdmin brings the most common administration and operations tasks into a single desktop app.

Installation (macOS DMG)

Download WeavyAdmin-X.X.X.dmg from the Releases page, open it, and drag WeavyAdmin to Applications.

First launch: macOS will block the app with a security warning because it is not notarized. To open it:

1. Click Done on the warning dialog
2. Go to System Settings → Privacy & Security
3. Scroll down to the Security section — you will see "WeavyAdmin was blocked"
4. Click Open Anyway

This is a one-time step per machine.

Run from Source

Requirements: Python 3.10+

git clone https://github.com/Shah91n/WeavyAdmin.git
cd WeavyAdmin
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

Optional tools (only needed for Kubernetes / cloud infra features):

Tool	Purpose
gcloud + kubectl	GCP GKE cluster access
aws + kubectl	AWS EKS cluster access
go	Flame graphs in pod/cluster profiling

Install these via your system package manager (Homebrew on macOS) and ensure they are on your PATH.

Features

• Dashboard — cluster health, quick-action grid, environment info, and enabled modules at a glance
• Node Details — verbose per-node info table
• Shards Details — all shards with search and filter
• Shards Indexing Status — view every shard replica, bulk set READONLY → READY, multi-select actions
• Shard Rebalancer — COPY/MOVE replica operations, compute and apply a balance plan, monitor replication operations (requires REPLICA_MOVEMENT_ENABLED=true)
• Collection Management — create (Custom Schema or CSV); bulk-delete via the sidebar × button with a multi-select picker, filter, and per-collection results
• Aggregation Report — per-collection / per-tenant counts with CSV export and a single-collection (or single-tenant) on-demand counter
• Schema Diagnostics — cluster health checks, shard consistency, compression and replication analysis
• Search Data — right-click any collection → choose BM25 keyword, Vector Similarity (near_text / near_vector), or Hybrid search; supports filters, metadata return, named vectors, and multi-tenancy
• RBAC Manager — create/edit/delete roles, manage DB users and OIDC groups, assign/revoke roles
• RBAC Report & Logs — aggregated insights and authorization audit log viewer
• Query Agent — natural-language chat using the Weaviate Query Agent (Weaviate Cloud only); supports Ask (generated answer), Search (retrieval only), and Suggest (propose example queries for the selected collections, with optional instructions and a configurable suggestion count)
• CSV Ingestion — drag-and-drop CSV import with MT and BYOV support; live log box reports per-batch progress and surfaces each failed object reported by Weaviate
• Backups — create, restore, cancel backups; usage statistics report
• Log Explorer — live-tail Kubernetes pod logs with structured columns and real-time search
• LB Traffic — HTTP Load Balancer / ALB traffic viewer for GCP and AWS
• StatefulSet — live Weaviate StatefulSet dashboard (replicas, resources, env vars, modules)
• Pods — pod list with status, restarts, and age; double-click to open a full Pod Detail tab
• Pod Detail — five-tab pod dashboard: Overview, Containers, Environment, Volumes, Events & Config
• Pod Profiling — Go pprof capture for a single pod with goroutine analysis and optional Claude AI review
• Cluster Profiling — batch pprof capture across all weaviate-* pods with per-pod progress

Project Structure

main.py              QApplication setup only
app/
  state.py             AppState — shared signals (connection_changed, namespace_changed)
  router.py            Maps (section, tool_name) → view class
  main_window.py       Mounts sidebar + workspace, connects router
  sidebar.py           Navigation tree
  workspace.py         Tab widget with unique-ID deduplication
  search_launcher.py   Orchestrates Search Data flow (MT check → type picker → tab open)
features/            One package per feature — view + worker, fully self-contained
  cluster/           Cluster info, backups, operations, raft, aggregation report
  collections/       Create, update config
  config/            Collection configuration viewer
  dashboard/         Cluster health overview
  diagnose/          Schema diagnostics
  ingest/            CSV import
  multitenancy/      Tenant availability + lookup
  objects/           Read, update, delete objects
  query/             Query agent
  rbac/              RBAC manager
  request_log/       Live HTTP/gRPC request log viewer
  schema/            Schema loader
  search/            BM25, vector similarity, hybrid search views + workers
  shards/            Shard indexing + rebalancer
  infra/             K8s/GCP/AWS views
    bridge/          Cloud auth worker
    cluster_profiling/ Batch pprof capture across all pods
    lb_traffic/      GCP + AWS load balancer traffic views
    logs/            Kubernetes log explorer
    pods/            Pod list + pod detail views
    profiling/       Single-pod pprof profiling
    rbac_analysis/   RBAC log analysis
    rbac_log/        RBAC audit log explorer
    statefulset/     StatefulSet overview
core/
  weaviate/          Pure Python Weaviate API wrappers (zero Qt)
    cluster/         Backups, health, meta, nodes, shard movement, statistics
    collections/     Aggregation, batch, create, delete, update
    multitenancy/    MT check, tenant activity, tenant lookup, tenant list
    search/          BM25, vector similarity, hybrid search core functions
    objects/         Delete, read, update
    agents/          Weaviate Agents — one module per agent (queryagent, …)
    rbac/            RBAC manager, report
    schema/          Diagnostics, schema, shards
  infra/             Pure subprocess wrappers for kubectl / gcloud / aws
    gcp/             GCP cluster bridge + LB traffic reader
    aws/             AWS cluster bridge + LB traffic reader
    profiling/       pprof bridge, profile parser, Claude analyzer
  connection/        Connection manager
shared/
  base_worker.py     QThread base with finished / error / progress signals
  worker_mixin.py    WorkerMixin — single copy
  request_logger.py  HTTP/gRPC request capture
  models/
    dynamic_weaviate_model.py  QAbstractTableModel for Weaviate object data
  styles/
    global_qss.py    GLOBAL_STYLESHEET + colour constants
    infra_qss.py     INFRA_STYLESHEET + infra colour constants
dialogs/             Shared QDialogs — not owned by any single feature
res/
  images/            App icons and images

Dependencies

Package	Purpose
weaviate-client[agents]	Weaviate API (agents extra included)
PyQt6	GUI framework
requests	HTTP operations
python-dotenv	Environment variable loading

Optional

Tool / Package	Feature
gcloud, kubectl	GCP GKE bridge
aws (v2), kubectl, wcs	AWS EKS bridge
weaviate-client[agents]	Query Agent (pip install 'weaviate-client[agents]')
go	SVG flame-graphs in Pod/Cluster Profiling
anthropic	AI-assisted goroutine analysis (pip install anthropic)

Timeout Settings

Configurable in the connection dialog (Timeout Settings tab):

Setting	Default
Init timeout	30 s
Query timeout	60 s
Insert timeout	120 s

Increase Query/Insert timeouts if you see WeaviateQueryError: timed out on large datasets.

Code Quality

ruff check --fix .
ruff format .
ruff check .

Pre-commit hooks run this automatically on git commit. Config: ruff.toml, .pre-commit-config.yaml.