Skip to main content
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: 
{
  "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 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:
VariableDefaultDescription
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_LEVELinfoControls log verbosity (silent, info, debug). Set to silent to suppress all stderr output
LIOP_EXPECTED_PROVIDERS1Number 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_MS8000Maximum time (ms) to wait for the initial mesh discovery phase before proceeding
LIOP_MCP_COMPACT_TOOL_DESCRIPTIONStrueStrips verbose protocol metadata from tool descriptions, reducing token consumption by ~500 tokens per tool. Set to 0 to opt-out
LIOP_GRPC_PORT50051Override the default gRPC port for the internal RPC server
LIOP_WORKER_MAX_HEAP_MB64Maximum V8 heap size per worker thread (Heap Bomb defense)
LIOP_DOCKER_MAPfalseForce 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_MODEfalseEnables development heuristics, which automatically activates Docker port mapping if the Nexus URL points to local demo ports (13000/13001)
LIOP_DATASET_SCALE1Scaling 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.