🐦‍⬛ Corvus

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

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, Neo4j, and SurrealDB 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
├── 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:

   make setup

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 clean	Remove build artifacts

Local Sandbox Environment

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

make dev-up      # Start Agent + Sandbox containers
make dev-shell   # Enter the Sandbox (Ubuntu)
make dev-down    # Stop the environment

---

📚 Documentation

Detailed documentation is available in the clients/web/apps/docs/ directory. You can build and view it locally:

make docs-web-build
make docs-web-dev

---

🤝 Contributing

Contributions are welcome! Please read our CONTRIBUTING.md (if available) 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.)