🐦‍⬛ Corvus

A reactive, always-on agent platform for long-running orchestration workloads.

📊 Repository Stats

📈 Activity & Reach

🚀 Project Status

🛡️ Code Quality (SonarCloud)

---

Corvus is a highly extensible, multi-interface agentic platform designed to bridge the gap between AI autonomy and human supervision. Built with a robust Kotlin Multiplatform foundation and powered by a high-performance Rust runtime, Corvus provides a secure, sandboxed environment for AI agents to perform complex, multi-step tasks.

---

📖 Table of Contents

• Features
• Tech Stack
• Project Structure
• Getting Started
  • Prerequisites
  • Installation
  • Running the App
• Development
  • Useful Commands
  • Local Sandbox Environment
• Documentation
• Contributing
• License

---

✨ Features

• Multi-Interface Support: Interact with Corvus via CLI, a Compose Multiplatform Desktop app, or a web-based dashboard.
• Always-On Autonomy: A daemon mode for long-running agents that can handle background tasks and persistent orchestration.
• Secure Sandboxing: Execute dangerous commands safely within isolated Docker containers or restricted native runtimes.
• Standardized Identity (AIEOS): Support for AIEOS v1.1, allowing for portable and model-agnostic AI personas.
• Hybrid Memory Model: Pluggable memory backends including SQLite and MCP-backed Cerebro for high-context retrieval.
• Rich Integrations: First-class support for WhatsApp (via Meta Cloud API), git, npm, cargo, and more.

---

🛠️ Tech Stack

• Core Logic: Kotlin Multiplatform (KMP)
• Agent Runtime: Rust (High-performance sidecars and CLI)
• Desktop UI: Compose Multiplatform
• Web Stack: Astro, Vue 3, and Tailwind CSS
• Documentation: Starlight
• Build System: Gradle & Makefile

---

📂 Project Structure

This repository is organized as a monorepo:

corvus/
├── clients/
│   ├── agent-runtime/    # High-performance Rust Agent Core & CLI
│   ├── composeApp/       # Shared UI logic for Desktop/Mobile
│   ├── web/              # Web monorepo (Docs, Dashboard, Marketing)
│   ├── androidApp/       # Android specific wrapper
│   └── iosApp/           # iOS specific wrapper
├── modules/
│   ├── agent-core-kmp/   # Core Kotlin Multiplatform logic & contracts
│   └── cerebro/          # MCP-backed long-term memory service
├── dev/                  # Local development environment (Docker/Sandbox)
├── gradle/               # Build logic and configurations
└── Makefile              # Standard entry point for development tasks

---

🚀 Getting Started

Prerequisites

• JDK 21+ (for Kotlin/KMP)
• Rust 1.75+ (for Agent Runtime)
• Node.js 22+ & pnpm 10+ (for Web Apps)
• Docker (optional, for Sandboxing)

Installation

1. Clone the repository:

   git clone https://github.com/dallay/corvus.git
   cd corvus

2. Run the initial setup (Recommended first step):

   make setup

   This command provides an automated "setup UI" that:
   • ✅ Verifies your toolchain (Java, Node, pnpm, Rust, Docker).
   • 🔗 Installs repository-specific Git Hooks for automated formatting and quality checks.
   • 🔧 Configures internal AI agent settings and web dependencies.
   • 💻 Works seamlessly on Windows (via Git Bash/WSL) and Linux/macOS.

Running the App

Start the Compose Multiplatform Desktop application:

make run

---

🛠 Development

Useful Commands

We use a Makefile to standardize common operations:

Command	Description
make build	Full build with tests
make test	Run all tests (Kotlin & Rust)
make format	Apply code formatting (Spotless & Biome)
make check	Run format, lint, and tests
make sonar	Reproduce the local monthly Sonar workflow
make clean	Remove build artifacts

Local Sonar Review Workflow

Use make sonar when you need to reproduce the monthly Sonar review locally before relying on the hosted SonarCloud workflow. This command generates the same main coverage inputs used by CI before invoking the local scanner.

Prerequisites:

• SONAR_TOKEN exported in your shell
• sonar-scanner available on PATH
• The standard repo toolchain required by make check-tools
• Rust coverage tooling (cargo install cargo-llvm-cov and rustup component add llvm-tools-preview)
• Web dependencies installed under clients/web/node_modules (the target runs pnpm --dir clients/web install --frozen-lockfile for you)

What make sonar does:

1. Validates Sonar credentials and scanner prerequisites fail-closed;
2. Generates Kotlin Kover XML reports for modules/agent-core-kmp and clients/composeApp;
3. Installs dashboard web dependencies and generates dashboard LCOV coverage;
4. Generates Rust LCOV coverage at coverage/agent-runtime-coverage.lcov;
5. Runs scripts/sonar.sh with CI-aligned scanner arguments.

Local execution is intended to improve reproducibility and faster iteration, not to replace the hosted SonarCloud workflow as the repository’s final shared quality signal.

Local Sandbox Environment

To test agents in a controlled environment, you can spin up the local dev stack:

make dev-up      # Start proxy + Agent + Sandbox at http://corvus.localhost
./dev/cli.sh up-dashboard  # Swap the landing page for the dashboard UI on the same origin
make dev-shell   # Enter the Sandbox (Ubuntu)
make dev-down    # Stop the environment

---

📚 Documentation

Detailed documentation is available at:

• English Documentation
• Spanish Documentation

Local Documentation

You can also build and view the full documentation site locally:

• make docs-dev: Run the local development server with hot-reload.
• make docs-build: Build the production documentation site.

🔎 DeepWiki

🤝 Contributing

Contributions are welcome! Please read our CONTRIBUTING.md and ensure you run make check before submitting a Pull Request.

---

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

---

(Note: Corvus is currently in active development. Features and architecture are subject to evolution.)