nyxora 1.4.1 → 1.4.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +98 -65
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,51 +1,114 @@
|
|
|
1
1
|
# Nyxora Agent 🤖
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
|
+
[](#)
|
|
5
|
+
[](#)
|
|
6
|
+
[](#)
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
A **secure, non-custodial, AI-native Web3 and System Automation Agent** built with Node.js and React. Designed for autonomous workflows with a premium Glassmorphism UI dashboard and client-side key isolation. It operates under a strict **Human-in-the-Loop** execution model for financial transactions, requiring explicit operator approval for any on-chain action.
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
---
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
## Key Features
|
|
13
|
+
|
|
14
|
+
### Advanced Trading, Security & Operations (New in v1.4.1)
|
|
15
|
+
* **System Automation & Full OS Access**: Instruct the agent to read/write local files, run terminal commands, and browse the web natively.
|
|
16
|
+
* **NLP Security Policy**: Command Nyxora using natural language to set security boundaries (e.g., *"Never touch partition E"*). Nyxora autonomously enforces these rules.
|
|
17
|
+
* **Dynamic Plugin Manager**: Dynamically load community-built skills. Simply provide a GitHub Gist URL, and Nyxora will hot-load the third-party skill.
|
|
18
|
+
* **Anti-Rugpull & Security Scanner**: Nyxora can scan smart contracts via GoPlus Labs to detect Honeypots, Hidden Taxes, and malicious proxy upgrades before you buy.
|
|
19
|
+
* **Automated Limit Orders**: Set natural language rules (e.g., "Sell my PEPE if price drops below $0.001"). Nyxora runs a background cron monitor and executes the swap while you sleep.
|
|
20
|
+
* **PNL & Portfolio Tracking**: The AI scans your wallets and multiplies balances by live DEX prices to give you real-time Net Worth estimations.
|
|
21
|
+
|
|
22
|
+
### Core Features
|
|
10
23
|
* **Multi-LLM Support**: Seamlessly switch between Google Gemini, OpenAI, OpenRouter (unlimited models!), or local Ollama models dynamically.
|
|
24
|
+
* **Premium Glassmorphism UI**: A gorgeous, resizable split-pane interface with Pseudo-Generative UI widgets (`<BalanceWidget>`, `<MarketWidget>`, `<SwapWidget>`).
|
|
11
25
|
* **Round-Robin API Rotation**: Add up to 10 API keys via the dashboard. The system will auto-rotate them to prevent rate-limiting and token drain.
|
|
12
26
|
* **Deep Personalization**: Feed the agent custom rules via `user.md` and define its core persona via `IDENTITY.md`.
|
|
13
27
|
* **Multi-Lingual Auto-Sync**: The agent natively detects your language and replies in the exact same language automatically.
|
|
28
|
+
* **Omnichannel Approvals & Telegram Integration**: Connect Nyxora to a Telegram Bot to execute trades, check prices, and chat on the go. Approve transactions directly from Telegram inline buttons!
|
|
29
|
+
* **Multi-Chain Support**: Pre-configured support for Ethereum, Base, BSC, Arbitrum, Optimism, and Sepolia Testnet.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 📐 Architecture Workflow
|
|
34
|
+
|
|
35
|
+
This diagram shows how user interactions flow through the Nyxora Agent, from chat input to on-chain or OS execution:
|
|
36
|
+
|
|
37
|
+
```mermaid
|
|
38
|
+
graph TD
|
|
39
|
+
A[User Chat / Telegram Bot] -->|Natural Language Command| B(Nyxora LLM Core)
|
|
40
|
+
B --> C{Determine Required Skill}
|
|
41
|
+
C -->|Web3 Action| D[Web3 Skill Modules]
|
|
42
|
+
C -->|System Action| E[OS & Plugin Modules]
|
|
43
|
+
D --> F{Transaction Type}
|
|
44
|
+
F -->|Read-only| G[Fetch On-chain Data & Prices]
|
|
45
|
+
F -->|Write-action| H[Queue in Transaction Manager]
|
|
46
|
+
H --> I[Require Human-in-the-Loop Approval]
|
|
47
|
+
I -->|Approved| J[Broadcast to Blockchain]
|
|
48
|
+
I -->|Rejected| K[Cancel Transaction]
|
|
49
|
+
E --> L{Security Policy Check}
|
|
50
|
+
L -->|Violates Policy| M[Ask Explicit Permission]
|
|
51
|
+
L -->|Safe| N[Execute Shell / File Ops]
|
|
52
|
+
G --> O[Render Dashboard UI / Chat Response]
|
|
53
|
+
J --> O
|
|
54
|
+
K --> O
|
|
55
|
+
N --> O
|
|
56
|
+
```
|
|
14
57
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
* **
|
|
23
|
-
* **
|
|
24
|
-
* **
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
* **PNL & Portfolio Tracking**: The AI scans your wallets and multiplies balances by live DEX prices to give you real-time Net Worth estimations.
|
|
28
|
-
* **DeFi Token Swapping & Bridging**: The agent can autonomously simulate liquidity routes and execute token swaps or cross-chain bridges with gas fee estimations.
|
|
29
|
-
* **Automated Limit Orders (Take-Profit/Cut-Loss)**: Set rules (e.g., "Sell my PEPE if price drops below $0.001"). Nyxora runs a background cron monitor and automatically executes the swap while you sleep without requiring manual approval!
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## 🛡️ Safety Model
|
|
61
|
+
|
|
62
|
+
To protect user assets and prevent common security concerns associated with AI agents, `Nyxora` operates under a strict safety specification:
|
|
63
|
+
|
|
64
|
+
* **No .env Leaks**: Your Private Key is encrypted using `AES-256-GCM` and locked behind a custom Master Password in `~/.nyxora/keystore.json`.
|
|
65
|
+
* **No Credential Collection**: Private keys are handled strictly within local volatile memory and are never transmitted to LLM providers.
|
|
66
|
+
* **Explicit Transaction Confirmation**: Write actions (like transfers, swaps, bridges) require manual, explicit confirmation from the human operator via the Web Dashboard or Telegram before broadcasting.
|
|
67
|
+
* **Human-in-the-Loop Execution**: The tool is engineered as a secure operational utility. The AI agent acts as a command generator, leaving financial execution authority with the human controller.
|
|
68
|
+
|
|
69
|
+
---
|
|
30
70
|
|
|
31
|
-
|
|
32
|
-
* **NLP Security Policy**: Command Nyxora using natural language to set security boundaries (e.g., *"Never touch partition E" or "Do not install global packages"*). Nyxora autonomously enforces these rules and will pause to ask for your explicit permission if an action violates them.
|
|
33
|
-
* **Full OS Access**: Instruct the agent to read/write local files, run terminal commands, and browse the web natively.
|
|
34
|
-
* **Plugin Manager**: Dynamically load community-built skills. Simply provide a GitHub Gist URL, and Nyxora will download, install, and hot-load the third-party skill directly into its `external_skills` directory.
|
|
71
|
+
## 📋 Example Safe Workflows
|
|
35
72
|
|
|
36
|
-
|
|
37
|
-
* **Premium Glassmorphism UI**: A gorgeous, resizable split-pane interface.
|
|
38
|
-
* **Pseudo-Generative UI**: Instead of raw text, the agent dynamically renders interactive widgets (`<BalanceWidget>`, `<MarketWidget>`, `<SwapWidget>`) onto the "Live Canvas" when executing Web3 skills.
|
|
39
|
-
* **JARVIS Voice Mode**: Completely hands-free! Uses browser Native Text-to-Speech (TTS) to read AI responses and Auto-Listen loops to capture your next voice command without clicking.
|
|
73
|
+
The agent is designed for Web3 exploration, daily operations, and secure transaction execution. Typical workflows include:
|
|
40
74
|
|
|
41
|
-
|
|
42
|
-
*
|
|
75
|
+
* **Audit New Tokens**: Tell the AI, *"Check if the contract 0x... on Base is safe to buy."*
|
|
76
|
+
* **Track Portfolio Assets**: Tell the AI, *"What is my total net worth across all chains right now?"*
|
|
77
|
+
* **Automate Trading**: Tell the AI, *"Create a limit order to sell 1000 USDC for ETH if ETH drops below $3000."*
|
|
78
|
+
* **System Operations**: Tell the AI, *"Check my computer's RAM usage and save it to stats.txt."*
|
|
43
79
|
|
|
44
|
-
|
|
80
|
+
---
|
|
45
81
|
|
|
46
|
-
|
|
82
|
+
## 🔒 Security, Threat Model & Permission Boundary
|
|
47
83
|
|
|
48
|
-
|
|
84
|
+
This agent is designed with a **Zero-Knowledge to LLM** architectural pattern to ensure the highest levels of security:
|
|
85
|
+
|
|
86
|
+
* **Zero-Knowledge to AI Agent (LLM)**: Remote AI Agents and Large Language Models (LLMs) **never** handle your private keys. The LLM only generates structured JSON tool calls.
|
|
87
|
+
* **Cryptographic Memory Isolation**: Transaction signing occurs strictly client-side within the local Node.js process runtime using `viem`.
|
|
88
|
+
|
|
89
|
+
### 🛡️ Threat Model
|
|
90
|
+
* **NLP Sandboxing**: System access is bounded by plain-text rules defined in `security_policy.md`. The AI evaluates its own actions against this policy before execution.
|
|
91
|
+
* **Strict API Auth**: The local Express server is protected via ephemeral Session Tokens (`x-nyxora-token`) and Strict CORS.
|
|
92
|
+
* **Non-Autonomous Financials**: The tool never executes unsolicited on-chain actions. Every financial transaction is queued pending human approval.
|
|
93
|
+
|
|
94
|
+
### 📋 Permission Boundary Matrix
|
|
95
|
+
|
|
96
|
+
| Access Category | Permission Boundary | Rationale |
|
|
97
|
+
| :--- | :--- | :--- |
|
|
98
|
+
| **Read Access** | Read-Only Blockchain Queries | Fetching balances, contract security audits, transaction logs, and technical indicators. |
|
|
99
|
+
| **Write Access**| Optional Wallet Signing | Required **only** for broadcasting transactions (swap, bridge, mint, transfer). Locked behind Human Approval. |
|
|
100
|
+
| **Network Access**| Bounded Public APIs | Restricted strictly to the configured RPC endpoints, Block Explorers, DexScreener, and LLM APIs. |
|
|
101
|
+
| **System Access**| Local Machine Access | Governed entirely by `security_policy.md`. The agent can run OS commands but will halt if it detects a policy violation. |
|
|
102
|
+
|
|
103
|
+
For the full detailed security specifications, contact info, and vulnerability reporting procedures, refer to the [SECURITY.md](SECURITY.md) policy document.
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## 🚀 Quick Start & Installation
|
|
108
|
+
|
|
109
|
+
Nyxora is available on NPM and can be installed as a global CLI tool on your operating system.
|
|
110
|
+
|
|
111
|
+
### 1. Global Installation
|
|
49
112
|
Open your terminal (Command Prompt, PowerShell, or Linux Terminal) and run:
|
|
50
113
|
```bash
|
|
51
114
|
npm install -g nyxora
|
|
@@ -56,39 +119,9 @@ No need to navigate to any specific folder! Just type:
|
|
|
56
119
|
```bash
|
|
57
120
|
nyxora
|
|
58
121
|
```
|
|
59
|
-
On first launch, Nyxora will greet you with an **Interactive Setup Wizard**. This CLI wizard will guide you to securely configure your LLM providers, API keys, and
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
1. Initialize a secure vault in your `~/.nyxora/` directory.
|
|
63
|
-
2. Store your Wallet Private Key securely in an encrypted `~/.nyxora/keystore.json` locked by your Master Password.
|
|
64
|
-
3. Store operational data (API Keys, RPCs) in `~/.nyxora/config.yaml`.
|
|
65
|
-
4. Start the local server, generate a secure Session Token, and open the Web Dashboard automatically!
|
|
66
|
-
|
|
67
|
-
> 💡 **Tip:** You can invoke the setup wizard at any time to update your keys by running `nyxora setup`.
|
|
68
|
-
|
|
69
|
-
### 3. Configuration
|
|
70
|
-
When the dashboard opens, you can modify any operational parameters in the **Settings** tab. The dashboard allows you to type custom model names, switch RPCs, and rotate your API keys effortlessly.
|
|
71
|
-
|
|
72
|
-
## Local Development (For Contributors) 🏗️
|
|
73
|
-
|
|
74
|
-
If you want to modify Nyxora's code, build new skills, or contribute:
|
|
75
|
-
|
|
76
|
-
1. Clone the repo:
|
|
77
|
-
```bash
|
|
78
|
-
git clone https://github.com/perasyudha/Nyxora.git
|
|
79
|
-
cd Nyxora
|
|
80
|
-
```
|
|
81
|
-
2. Install dependencies:
|
|
82
|
-
```bash
|
|
83
|
-
npm install
|
|
84
|
-
cd dashboard && npm install && cd ..
|
|
85
|
-
```
|
|
86
|
-
3. Run the development build:
|
|
87
|
-
```bash
|
|
88
|
-
npm run build && npm run start
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
*To deploy your own branch to NPM, bump the version and run `npm run deploy`!*
|
|
122
|
+
On first launch, Nyxora will greet you with an **Interactive Setup Wizard**. This CLI wizard will guide you to securely configure your LLM providers, API keys, and Master Password Wallet.
|
|
123
|
+
|
|
124
|
+
The system will automatically initialize a secure vault in your `~/.nyxora/` directory and open the Web Dashboard in your browser!
|
|
92
125
|
|
|
93
126
|
## Architecture
|
|
94
127
|
* **Backend**: Node.js, Express, Viem (Web3), node-telegram-bot-api, OpenAI API.
|