NexoraControl

NexoraControl is a distributed server monitoring and control system built with Django, Python, and PySide6.

Features

• Backend (Django REST Framework, PostgreSQL): Agent registration and authentication, API endpoints for command lifecycle, agent recovery handling, and Docker Compose deployment support.
• Agent (Python): Automated installation (bash/systemd), CPU and RAM monitoring, online/offline detection, remote command execution (Docker and system commands).
• Desktop Client (PySide6): Visual agent monitoring, centralized command management, asynchronous REST API communication, and background processing.

System Architecture

Click to view Sequence Diagram

sequenceDiagram
    autonumber

    participant GUI as Desktop Client
    participant API as Django API
    participant DB as PostgreSQL
    participant Agent as Nexora Agent

    Note over GUI,DB: Agent registration
    GUI->>API: POST /agents/
    API->>DB: Create Agent
    DB-->>API: Agent data
    API-->>GUI: Agent ID + token

    Note over Agent,DB: Monitoring
    loop Every 5 seconds
        Agent->>API: POST /agents/{id}/heartbeat/
        API->>DB: Update status and metrics
        DB-->>API: Updated state
        API-->>Agent: 200 OK
    end

    Note over GUI,Agent: Command execution
    GUI->>API: POST /agents/{id}/commands/
    API->>DB: Create pending command
    DB-->>API: Command created
    API-->>GUI: 201 Created

    loop Command polling
        Agent->>API: GET /agents/{id}/commands/pending
        API->>DB: Query pending commands
        DB-->>API: Pending commands
        API-->>Agent: Commands
    end

    Agent->>Agent: Validate command
    Agent->>Agent: Execute command
    Agent->>API: PATCH /agents/{id}/commands/results/
    API->>DB: Update command result
    DB-->>API: Updated command
    API-->>Agent: 200 OK

    GUI->>API: GET /agents/
    API->>DB: Query agents
    DB-->>API: Agent state
    API-->>GUI: Agents data

Loading

Installation

1. Backend Server

On the VPS:

Install Docker: https://docs.docker.com/engine/install/

Clone the repository:

git clone https://github.com/kapusta123b/NexoraControl.git
cd NexoraControl

Edit environment variables:

nano .env

Update Nginx server name:

nano conf.d/nginx.conf

Build and start containers:

docker compose up -d --build

Apply migrations:

docker exec web python manage.py migrate

2. Agent

On the VPS you want to monitor:

curl -fsSL https://raw.githubusercontent.com/kapusta123b/NexoraControl/main/agent/install.sh | sudo bash

The installer downloads the Agent, creates its virtual environment, installs dependencies, configures systemd, and starts the initial setup. During setup, provide the Backend API URL and machine name.

Check the Agent status:

sudo systemctl status nexora-agent

View logs:

sudo journalctl -u nexora-agent -f

3. Desktop

Run the Desktop Client:

cd desktop
python -m venv venv
source venv/bin/activate  # For Linux/macOS. For Windows: venv\Scripts\activate
pip install -r requirements.txt
python main.py

The Desktop Client connects to the Django API and provides monitoring and control of registered Agents.

License

MIT