CROW-Client

CROW (Cron-Routine-Orchestrator-Webapp) is a distributed task execution and orchestration system. This repository contains the CROW-Client, a lightweight WebSocket-based agent that runs on client machines to execute tasks dispatched by the CROW-Server.

🎯 Overview

CROW-Client is a Python-based task execution agent that:

• Runs as a WebSocket server on the client machine
• Receives task execution requests from the CROW-Server
• Executes tasks with proper error handling and status reporting
• Provides real-time bidirectional communication via WebSockets
• Handles concurrent task requests asynchronously

✨ Features

• Async WebSocket Communication: Non-blocking WebSocket server for reliable task delivery
• Task Execution: Flexible task parsing and execution framework
• Error Handling: Comprehensive error handling with detailed status codes and messages
• Lightweight: Minimal dependencies - only requires asyncio, pydantic, and websockets
• Production-Ready: Type-safe request/response validation using Pydantic
• Easy Integration: Simple CLI startup and configuration

🚀 Installation (Linux, macOS, Windows)

CROW Client can be installed with a single command on all major operating systems. The installer scripts are fetched directly from this repository and executed locally.

⚠️ Security Note

This executes a remote script from this repository. Only run it if you trust the source.

---

Linux / macOS (bash)

Linux

curl -fsSL https://raw.githubusercontent.com/Cron-Routine-Orchestrator-Webapp/CROW-Client/main/installer/install_linux.sh | bash

macOS:

curl -fsSL https://raw.githubusercontent.com/Cron-Routine-Orchestrator-Webapp/CROW-Client/main/installer/install_macos.sh | bash

---

Windows (PowerShell)

Run in PowerShell:

iwr https://raw.githubusercontent.com/Cron-Routine-Orchestrator-Webapp/CROW-Client/main/installer/install_windows.ps1 -UseBasicParsing | iex

---

What this does

Each installer will:

• Fetch the latest release from GitHub
• Download the correct platform ZIP asset
• Extract the crow-client executable
• Install it into a user-local directory
• Register it for auto-start:
  • Linux: systemd --user
  • macOS: launchd
  • Windows: Startup folder shortcut
• The client will start and listen on 0.0.0.0:1237 for incoming task requests from the CROW-Server.

---

File locations after install

• Linux: ~/.local/share/crow-client
• macOS: ~/Library/Application Support/crow-client
• Windows: %APPDATA%\crow-client

---

Updating

Re-run the same command to update to the latest version. The installer will replace the existing installation with the newest release automatically.

🏗️ Architecture

CROW-Client Architecture:
┌─────────────────────────────────────┐
│      WebSocket Server (Port 5000)   │
│       Listens for task requests     │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      Request Parser & Validator     │
│    (Using Pydantic Models)          │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      Task Executor                  │
│   Parses and executes commands      │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│   Response Builder & Sender         │
│   Returns status + execution output │
└─────────────────────────────────────┘

📋 Requirements

• Python: 3.10 or higher
• Dependencies:
  • asyncio >= 4.0.0 - Asynchronous I/O support
  • pydantic >= 2.13.4 - Data validation and serialization
  • websockets >= 16.0 - WebSocket protocol implementation

📂 Project Structure

src/client/
├── __init__.py              # Package initialization
├── __main__.py              # Entry point - starts WebSocket server
├── communication/
│   ├── __init__.py
│   └── web_sockets.py       # WebSocket server implementation
├── exec_handling/
│   ├── __init__.py
│   └── executor.py          # Task execution logic
└── helper/
    ├── __init__.py
    └── types.py             # Pydantic models (Request, Response)

🔌 Communication Protocol

Request Format

The client expects requests in JSON format matching the Request model:

• PID: Process ID for tracking
• ACTION_TYPE: Type of action to execute
• [other fields]: Action-specific parameters

Response Format

Responses are sent back in JSON format with:

• STATUS: "success" or "error"
• CODE: HTTP-style status code (200, 500, etc.)
• PID: Process ID from the request
• ACTION_TYPE: The action that was executed
• OUTPUT: Execution result or error message

📚 Documentation

For detailed documentation and API reference, visit:

• Documentation (DeepWiki)
• CROW-Server Documentation

🔗 Related Projects

• CROW-Server - The orchestration server that dispatches tasks to clients
• CROW Organization - Main organization repository

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details on:

• How to submit issues
• How to create pull requests
• Code standards and best practices

📜 Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct.

📄 License

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

📞 Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check the documentation
• Review existing discussions in the repository