QonQrete - Secure AI Construction Loop System

QonQrete is a Secure AI Construction Loop System, using a Multi-Agent Pipeline Orchestrator in a Sandbox environment with YAML Configuration. In short: it spawns 3 AI agents in a sandbox/container and makes them work together on tasks. It can run with a hard requirement for user approval between steps, or in a fully autonomous mode where it keeps running until the user decides to stop it.

QonQrete is a multi-agent orchestration system designed for secure, observable, and human-in-the-loop software construction. It operates on the principle of a secure build environment (Qage), managed by a host-level orchestrator (Qrane).

This architecture ensures that AI-generated code and processes cannot affect the host system, providing a robust framework for autonomous and semi-autonomous development.

Version

Version: v0.5.0-beta (See VERSION file for the canonical version).

Note on TUI Mode and Agent Testing:

The Text-based User Interface (TUI) mode is currently under active development and may still have bugs. While the agent setup is dynamic, extensive testing is still required.

We welcome community contributions! If you encounter any issues or have suggestions, please report them. Your feedback is invaluable in helping us improve the system.

Core Principles

1. Isolation by Design: All agent execution occurs within the Qage, a Docker container that acts as a secure sandbox. The Qrane, running on the host, manages the workflow.
2. Configuration-Driven: The agent models and cycle limits are defined declaratively in worqspace/config.yaml.
3. File-Based Communication: Agents communicate by reading and writing markdown files to a shared worqspace/ volume, creating a transparent and auditable "chat history".
4. Human-in-the-Loop Control: By default, a non-negotiable CheQpoint pauses the system after each cyQle. The user, acting as the gateQeeper, must review the results and provide explicit instructions to [Q]ontinue, [T]weaQ, or [X]Quit. This behavior can be configured to be autonomous by default.

Architecture Overview

• qrane/: Contains the Python-based Qrane orchestrator and its command-line interface.
• worqer/: Contains the individual AI agent scripts (instruQtor, construQtor, inspeQtor).
• worqspace/: The shared data plane. It contains all configuration, the initial tasQ, and all generated plans (briQ), summaries (exeQ), and reviews (reQap).

The Workflow CyQle

A cyQle consists of three main phases, orchestrated by the Qrane:

1. Plan (instruQtor): A gpt-4o-mini agent reads the high-level tasQ and creates a series of markdown briQ files, which contain a detailed, high-level plan for the executor agent.
2. Execute (construQtor): A gemini-2.5-flash agent is invoked for each briQ. It reads the high-level plan and uses its own powerful agency and tools to generate all necessary files and code in the qodeyard/ directory.
3. Review (inspeQtor): A gpt-4o-mini agent reviews the code generated by the construQtor, assesses its quality, and produces a final reQap (review) with an assessment and suggestions for the next cycle.
4. CheQpoint (gateQeeper): The Qrane pauses the system and displays the reQap, waiting for the user's command to proceed.

System Requirements

The Qrane orchestrator runs directly on the host, while the Qrew of AI agents runs inside a sandboxed container.

1. Docker

Docker is the default, essential runtime for the secure Qage environment.

• macOS: Install Docker Desktop for Mac.
• Linux:
  • Debian/Ubuntu: sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io
  • Fedora/CentOS: sudo dnf install dnf-plugins-core && sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo && sudo dnf install docker-ce docker-ce-cli containerd.io
• Windows: Install Docker Desktop for Windows.

Note for Docker Desktop (macOS & Windows) Users: You MUST grant Docker permission to access the project directory. Go to Settings > Resources > File Sharing and add the path to your qonqrete project folder. This allows the worqspace volume to be mounted correctly.

2. Microsandbox (Optional)

As a lightweight alternative to Docker, you can use msb.

• Installation: Follow the instructions at the official Microsandbox repository.
• You can set msb as the default runtime in worqspace/pipeline_config.yaml.

Getting Started

For a full guide on setting up the environment and running your first cyQle, please see QUICKSTART.md.

API Key Configuration: Before running, you must export the API keys for the AI providers you intend to use. The system will automatically check for the necessary keys based on your worqspace/config.yaml.

• export OPENAI_API_KEY='your-key'
• export GOOGLE_API_KEY='your-key' (or GEMINI_API_KEY)
• export ANTHROPIC_API_KEY='your-key'
• export DEEPSEEK_API_KEY='your-key'

First, initialize the system. This builds the secure container environment.

# For Docker (default)
./qonqrete.sh init

# If you use Microsandbox
./qonqrete.sh init --msb

To run the system with the Text-based User Interface (TUI) and set an operational mode:

./qonqrete.sh run --tui --mode security

To run in autonomous mode with a specific task granularity:

./qonqrete.sh run --auto --briq-sensitivity 2

To force user-gated mode (overriding a config file set to auto):

You can override the configured runtime using flags:

# Force run with Microsandbox
./qonqrete.sh run --msb

# Force run with Docker
./qonqrete.sh run --docker

To clean up the workspace and remove all previous run data:

# Force run with Microsandbox
./qonqrete.sh run --msb

# Force run with Docker
./qonqrete.sh run --docker

To clean up the workspace and remove all previous run data:

License

QonQrete is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This ensures that any modifications or derivative works deployed as a service must also be released as open source under the same license. See the LICENSE file for full text.