Nous

Nous is a Windows-focused remote administration tool that lets you control one or more listener PCs from a single host machine using natural-language prompts. A desktop UI (Nous.exe) on the host talks to a Python backend and MySQL database, while lightweight listener agents receive commands and stream results back.

Key features

• Natural language control: Type a prompt, generate a command, and send it to remote machines.
• Multiple LLM backends: Switch between Gemini, Groq, or local Ollama by adjusting environment variables and backend provider selection.
• Secure listener registration: Remote machines register via hash codes and certificates (cert.pem), so only approved listeners receive commands.
• MySQL-backed state: IPs and hashes are stored in a MySQL database and refreshed on a countdown timer.

Tech stack

• Desktop UI (host): C# / .NET 9 with Avalonia (Nous.sln, Nous.exe)
• Python services:
  • Flask + Flask-CORS API (api_server.py)
  • LangChain + FAISS vector database (backend.py, create_vector_db.py)
  • Utility scripts and logging (explainer.py, Utils/Logger.py, Sanitizer.py)
• LLM integrations:
  • Google Gemini via google-generativeai / langchain-google-genai
  • Groq via the groq Python SDK
  • Local Ollama via the ollama Python client
• Data & storage:
  • MySQL (schema managed by db_setup.sql, ip_hash table)
  • YAML-based knowledge data in data/ (RAG sources)
• Remote listeners:
  • Listener_v2.1.0 (standard)
  • HYPER-Listener_v2.1.0 (administrator build)

LLM configuration

• Supported providers: Gemini, Groq, Ollama (local).
• Environment variables are defined in .env (see .env.example).
• To change provider, set the relevant API key(s) and update the backend provider selection in backend.py.

Nous Setup

Follow these steps in order to bring up the application end to end.

1. Git clone

   git clone <repo-url>

2. Change directory

   cd Nous

3. Open Visual Studio
   Make sure the .NET Desktop Development workload is installed before proceeding.

4. Install Python requirements

   pip install -r requirements.txt

5. Create the vector database (one time)

   python create_vector_db.py

6. Run dotnet restore

   dotnet restore

7. Create the .env file
   Copy .env.example to .env and set every environment variable it lists. This is also where you choose your LLM provider (Gemini, Groq, or local Ollama). Provide the matching API key for Gemini or Groq; Ollama runs locally and needs no key. Update the backend’s provider selection to match your choice.

8. Create the MySQL database

   mysql -u <user> -p -e "CREATE DATABASE nous;"

9. Run the setup script through mysqlsh
   From the project directory execute

   mysqlsh --user <user> --host <host> --password --database <db> --sql -f db_setup.sql

   Replace the placeholders and enter the password when prompted. This builds the table required by the app.

10. Extract cert.pem
    Grab cert.pem from Listener_v2.1.0 or HYPER-Listener_v2.1.0 (administrator version) and place it in the project root.

11. Build the Avalonia solution
    In Visual Studio (or VS Code with the C# extension) select Nous.sln as the startup item and build the app.

12. Prepare the listener PC
    On the remote machine extract Listener_v2.1.0 or HYPER-Listener_v2.1.0 (administrator version) and install its requirements.txt:

    pip install -r requirements.txt

13. Verify connectivity
    Ping from host to remote and remote to host. If packets fail, adjust inbound firewall rules or temporarily disable the firewall.

14. Launch the host executable
    On the host run:

    Nous\bin\Debug\net9.0\Nous.exe

15. Start the API server
    In the UI click Start Server to bring up the Flask API used for database updates.

16. Wait for the countdown
    The countdown controls when listener hash entries refresh; they update once it hits zero.

17. Configure the listener
    On the remote PC open the listener in edit mode, enter the host IP plus port, and save.

18. Register the listener
    Start the listener so it calls the host API and registers its IP addresses in the host database.

19. Control access and send commands

    • In Access Gate on the host, enter the remote PC’s hash code (add multiple hashes if you manage several machines).
    • Enter a prompt, click Generate to build the command, then Send. The remote PC executes the command and returns output to the Access Gate window.

Note: Follow these exact steps to ensure the application runs correctly from host to listener.