Axil

The desktop cockpit for Arbora.
_{A unified, visual control deck over the Arbora multi-agent ecosystem.}

Documentation · Architecture · Concepts

Version: 5.2.2

Overview

The repository is axil; the package, imports and executable remain axil. Existing icon assets and screenshot provenance are retained.

Axil is a desktop GUI application and visual control deck the desktop frontend of the ecosystem. It reaches data and agents only through Arbora, the one door for served operations, admission and authentication. It integrates every specialist agent and MCP package in the fleet into a single-pane-of-glass user interface, offering 1-click execution, embedded hybrid terminals, zero-nesting visual layouts, and a zero-trust hardware protection layer.

Axil provides a centralized graphical cockpit designed to eliminate tedious click-through fatigue. It maps specialist agent parameter schemas directly to custom QSS-themed form widgets on the fly.

Operators can trigger actions, monitor running terminal inputs via the embedded tuig, and secure dangerous CLI calls using the Zero-Trust Tool-Guard interceptor.

Key Capabilities

• Dynamic, schema-driven control panels for every specialist agent and MCP package in the fleet.
• An embedded hybrid terminal (xterm.js) for interactive, in-cockpit sessions.
• A zero-trust Tool-Guard that intercepts and confirms sensitive mutations before execution.
• Ask-Data (NL→Query), engine metrics/PromQL, and federated search through Arbora.
• A fleet supervisory cockpit: worker topology and the ActionPolicy approval inbox.

Table of Contents

1. Overview
2. Key Capabilities
3. Features
4. Architecture
5. Installation
6. Usage
7. Packaging & Executables
8. Documentation References
9. License

---

✨ Features

• Zero-Nesting Dynamic UI: Navigation categorized into flat category menus (Dashboard, Infra, Media, Productivity, Research).
• Dynamic Card Schema Grid: PySide6 widgets are built automatically from specialist agent tool specifications.
• Embedded Hybrid Terminal: Hosts local xterm.js to run interactive terminal loops directly in the cockpit.
• Zero-Trust Security Tool Guard: Prompts native authorization dialogs to review arguments before executing dangerous mutations.
• Runnable Background Workers: Utilizes thread pools (QThreadPool) to prevent GUI freezes during execution loops.
• Visual Trading Dashboard: Snappy native C++ charting engine (PySide6.QtCharts) with OHLCV candlestick/line toggles, strategy indicator overlay crossovers (MACD/RSI), orderbook bids/asks depth volumes, and thread-safe crypto news feeds.
• Ask Data (NL→Query): Ask Medulla a question in plain English; the engine generates an auditable read-only query (UQL/Cypher/SQL/SPARQL), runs it, and synthesizes an answer with citations — over the gateway /api/graph/ask-data and /api/graph/nl-query routes.
• Engine Metrics & Status: Query engine observability with PromQL (/api/graph/promql) and watch the shared content-addressed KV-cache occupancy (/api/graph/kvcache).
• Federated Search: Fan one query across every registered external graph and rank the merged results (/api/graph/federated-search).

---

🏛️ Architecture

Axil is a PySide6 GUI client. It holds no store and no agent logic. It calls Arbora through arbora.client. Arbora fronts Medulla (the knowledge engine) and the Meristem in-run harness.

graph TD
    subgraph GUI ["Axil Cockpit (PySide6)"]
        Sidebar["Left Category Sidebar"]
        GridDeck["Central Dynamic Card Grid"]
        ToolGuard["Tool Guard Modal Interceptor"]
        TerminalPanel["xterm.js WebEngine Panel"]
    end

    subgraph Backend ["Arbora (the one door)"]
        Discovery["Agent Specialist Discovery"]
        Executor["Background Agent Worker Loop"]
        KG["Medulla knowledge engine"]
    end

    Sidebar --> GridDeck
    GridDeck -->|Introspect Schemas| Discovery
    GridDeck -->|Trigger Safe Action| Executor
    GridDeck -->|Sensitive Action| ToolGuard
    ToolGuard -->|Operator Approved| Executor
    TerminalPanel -.->|Interactive Terminal| Executor

Loading

Detailed architectural diagrams and component breakdowns are located in the Documentation Overview.

---

🛠️ Installation

1. Modern Virtual Environment (via uv)

Create a virtual environment and sync standard requirements:

# Setup virtual environment
uv venv

# Sync requirements
uv pip sync requirements.txt

2. Standard pip

Install standard stable packages:

pip install axil

Install with all ecosystem plugins:

pip install axil[all]

---

🌍 Environment Variables

Axil can be configured using environment variables or a .env file in the project root:

Variable	Description	Default / Example
QT_QPA_PLATFORM	Headless Qt Platform (set to offscreen for CI/CD or Docker)	offscreen
LANGFUSE_PUBLIC_KEY	Langfuse Observability Public Key	pk-lf-...
LANGFUSE_SECRET_KEY	Langfuse Observability Secret Key	sk-lf-...
LANGFUSE_HOST	Langfuse Host URL	https://cloud.langfuse.com
LOGFIRE_TOKEN	Pydantic Logfire Telemetry Token
TERM	Terminal type for the embedded terminal emulator	xterm-256color
_MEIPASS / _MEIPASS2	PyInstaller temp directories for bundled app context	(Used internally)

---

🚀 Usage

Launch the desktop cockpit:

uv run axil

To run in headless or virtual Linux environments (CI/CD):

QT_QPA_PLATFORM=offscreen uv run axil

---

📦 Packaging & Executables

PyInstaller Compiling

Compiling Axil as a single standalone executable:

python -m pip install --upgrade pyinstaller
git clone https://github.com/Knuckles-Team/axil.git axil
cd axil
python -m venv .venv
./.venv/Scripts/activate
python -m pip install -r ./requirements.txt
python -m pip install -r ./build-requirements.txt
python -m pip install --upgrade pandas scipy numpy pydantic
pyinstaller --name axil `
  --log-level DEBUG `
  --onefile --windowed `
  --paths "./axil" `
  --icon='./axil/img/axil.ico' `
  --recursive-copy-metadata=opentelemetry_api `
  --recursive-copy-metadata=opentelemetry_sdk `
  --recursive-copy-metadata=opentelemetry_exporter_otlp_proto_grpc `
  --exclude-module pygame `
  --exclude-module tkinter `
   ./axil/axil.py

Windows Setup Installer

Generate a Windows MSI setup package:

iscc "./packaging/windows/setup.iss"

---

📚 Documentation References

For deep architectural guidelines and code documentation, explore:

• docs/index.md — Documentation Entrypoint & Quickstart.
• docs/overview.md — Detailed Architecture & Security Guardrails.
• docs/concepts.md — Concept Registries (CONCEPT:GB-GBOT.cockpit.gbot through 8.0).

Start at the Axil documentation for the hosted, always-current version of the same material.

---

Contributing

See AGENTS.md for contribution and validation guidance.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.