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:

npx -y @nekzus/liop@latest

Or install it globally to have the liop command available system-wide:

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:

Windows (%APPDATA%\Claude\claude_desktop_config.json)

{
  "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:

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 returns a structured operational 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 generating unnecessary network traffic 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_QUERY_BUDGET	(none)	Session query budget override for high-frequency analytical audit testing
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)

Dual-Era MCP Handshake Compliance

The LIOP Agent natively satisfies both modern and legacy MCP client protocols:

• MCP v2 Revision (2026-07-28):
  • Answers server/discover probes without authentication for stateless tool discovery.
  • Automatically includes mandatory resultType: "complete" in tools/list responses.
  • Handles subscriptions/listen and resources/templates/list without polling overhead.
• MCP Legacy Era (2025-11-25):
  • Strips v2 metadata via adaptResponseForLegacyClient() to prevent parsing failures in legacy desktop clients.

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.

---

Programmatic Mesh Integration (MeshNode)

Developers integrating LIOP into custom backend services can instantiate and manage MeshNode directly rather than invoking the CLI binary:

import { MeshNode } from "@nekzus/liop";

const mesh = new MeshNode({
  listenAddresses: ["/ip4/0.0.0.0/tcp/4001"],
  bootstrapNodes: [
    "/ip4/127.0.0.1/tcp/15001/p2p/12D3KooW..."
  ],
  enableWAN: false,
  enableAutoNAT: true,
  enableRelay: true,
});

await mesh.start();
console.log("Local Peer ID:", mesh.getPeerId());

// Discover remote enclaves announcing a specific tool capability
const providers = await mesh.findProviders("tool:execute_anomaly_audit");

// Query a remote node's capability manifest over /liop/manifest/1.0.0
for (const peerId of providers) {
  const manifest = await mesh.queryManifest(peerId);
  console.log(`Discovered ${manifest?.tools.length} tools on ${peerId}`);
}

// Graceful shutdown
await mesh.stop();

Key Public Methods

Method	Return Type	Description
start()	Promise<void>	Initializes libp2p transports, Noise crypto, and Kademlia routing
stop()	Promise<void>	Closes all active swarm sockets and flushes DHT routing state
getPeerId()	string	Returns the local node’s Ed25519 Peer ID string
getMultiaddrs()	string[]	Returns all bound transport multiaddrs (TCP/WS)
findProviders(capability)	Promise<string[]>	Queries Kademlia DHT for peer IDs advertising a capability
queryManifest(target)	Promise<LiopManifest | null>	Directly fetches signed JSON manifest from a remote peer
announceManifest(manifest)	Promise<void>	Publishes local capabilities to the DHT and registers manifest stream handler

If you encounter connection issues, check for the LIOP Guard banner in the console or ask the LLM to call LiopMeshStatus.