> ## Documentation Index
> Fetch the complete documentation index at: https://nekzus-32.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# LIOP Agent (CLI)
> Zero-Config security gateway for desktop AI applications
The **LIOP Agent** is a pre-compiled, production-ready CLI utility included with the `@nekzus/liop` package. It acts as a bridge between standard AI interfaces (like **Claude Desktop** or **Cursor**) and the decentralized **Logic-Injection-on-Origin Protocol**.
Instead of writing a custom server, users can simply run the agent to instantly gain "Logic-Injection-on-Origin" capabilities.
## Installation
The agent is distributed via the main SDK package. You can run it directly using `npx`:
```bash theme={null}
npx -y @nekzus/liop@latest
```
Or install it globally to have the `liop` command available system-wide:
```bash theme={null}
npm install -g @nekzus/liop@latest
liop
```
## 🤖 Claude Desktop Integration
LIOP is designed to be a drop-in replacement for MCP servers. To add LIOP tools to your Claude Desktop experience, update your configuration file:
```json Windows (%APPDATA%\Claude\claude_desktop_config.json) theme={null}
{
"mcpServers": {
"liop": {
"command": "npx",
"args": ["-y", "@nekzus/liop@latest"],
"env": {
"LIOP_NEXUS_URL": "http://your-nexus-host:3000",
"LIOP_TOKEN_BANK": "your-bank-token-here",
"LIOP_TOKEN_VAULT": "your-vault-token-here",
"LIOP_LOG_LEVEL": "info",
"NODE_OPTIONS": "--use-system-ca"
}
}
}
}
```
```json macOS (~/Library/Application Support/Claude/claude_desktop_config.json) theme={null}
{
"mcpServers": {
"liop": {
"command": "npx",
"args": ["-y", "@nekzus/liop@latest"],
"env": {
"LIOP_NEXUS_URL": "http://your-nexus-host:3000",
"LIOP_TOKEN_BANK": "your-bank-token-here",
"LIOP_TOKEN_VAULT": "your-vault-token-here",
"LIOP_LOG_LEVEL": "info",
"NODE_OPTIONS": "--use-system-ca"
}
}
}
}
```
Once configured, restart Claude Desktop. You will see the 🛡️ **LIOP Guard** status in your logs.
## Core Features
### 1. Identity Persistence
The agent generates a unique **PeerID** (Ed25519 keypair) the first time it runs. This identity is stored in:
`~/.liop/identity.json`
> \[!IMPORTANT]
> If you move to a different machine, copying this folder will allow you to keep your reputation and verified access across the Mesh.
### 2. Autonomous Routing
The agent uses the `LiopMcpRouter` internally. When a tool call is received from Claude:
1. It queries the **Kademlia DHT** to find nodes providing that tool.
2. It establishes a **Kyber768 + AES-256-GCM** secure tunnel.
3. It executes the logic on the remote server and returns the verified result.
### 3. Bootstrap Discovery
By default, the agent connects to the official **LIOP Alpha Nexus**. However, you can point it to any mesh bootstrap node:
```bash theme={null}
npx @nekzus/liop@latest /ip4/1.2.3.4/tcp/4001/p2p/PEER_ID
```
## Security & Diagnostics
The agent only communicates via **STDIO**. It prints status logs and discovery events strictly to `stderr`, ensuring that the `stdout` channel remains clean for valid JSON-RPC 2.0 messages required by the LLM client.
### Local Mesh Diagnostics (`LiopMeshStatus`)
The agent automatically exposes a local diagnostic tool called **`LiopMeshStatus`**. When an LLM calls this tool, the agent intercepts it locally instead of routing it over the P2P network. It instantly returns a rich, human-readable report detailing:
* Connected Bootstrappers and Peer IDs
* Active Nodes (Vault, Bank, Oracle)
* Tool routing tables and Kademlia DHT state
* Token consumption and telemetry estimates
This allows AI clients to autonomously diagnose connection drops or verify which tools are available without burning bandwidth or duplicating diagnostic requests across multiple nodes.
### Environment Variables
The agent behavior can be customized via the following environment variables:
| Variable | Default | Description |
| :----------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LIOP_NEXUS_URL` | *(none)* | URL of the Nexus node for Auto-Discovery. The agent resolves the PeerID and multiaddr from the `/health` endpoint automatically |
| `LIOP_LOG_LEVEL` | `info` | Controls log verbosity (`silent`, `info`, `debug`). Set to `silent` to suppress all stderr output |
| `LIOP_EXPECTED_PROVIDERS` | `1` | Number of mesh providers to wait for during initial warm-up. The adaptive DHT polling continues discovering additional providers in the background |
| `LIOP_INITIAL_DISCOVERY_TIMEOUT_MS` | `8000` | Maximum time (ms) to wait for the initial mesh discovery phase before proceeding |
| `LIOP_MCP_COMPACT_TOOL_DESCRIPTIONS` | `true` | Strips verbose protocol metadata from tool descriptions, reducing token consumption by \~500 tokens per tool. Set to `0` to opt-out |
| `LIOP_GRPC_PORT` | `50051` | Override the default gRPC port for the internal RPC server |
| `LIOP_WORKER_MAX_HEAP_MB` | `64` | Maximum V8 heap size per worker thread (Heap Bomb defense) |
| `LIOP_DOCKER_MAP` | `false` | Force translation of Docker-internal container IPs (`172.x.x.x`) to the host loopback (`127.0.0.1`), mapping target gRPC services to host-published ports for running containerized mesh nodes in local environments |
| `LIOP_DEV_MODE` | `false` | Enables development heuristics, which automatically activates Docker port mapping if the Nexus URL points to local demo ports (`13000`/`13001`) |
| `LIOP_DATASET_SCALE` | `1` | Scaling factor used by test and demo nodes to dynamically scale synthetic record generation size (e.g., bank transactions, health records) |
`LIOP_BOOTSTRAP_FILE` is **deprecated** since v2.0.0-alpha. Use `LIOP_NEXUS_URL` instead. The agent will log a warning if this variable is detected.
If you encounter connection issues, check for the 🛡️ icon in the console or ask the LLM to call `LiopMeshStatus`.