Package Exports

@decentnetwork/lan

Readme

Decent AgentNet

A private network layer for self-hosted AI agents, built on Elastos Carrier.

Decent AgentNet lets machines behind NAT, firewalls, or customer-controlled networks communicate securely with private virtual IPs (10.86.0.0/16), without requiring public IPs, port forwarding, or remote desktop access.

Perfect for:

Remote agent support — Service providers accessing customer OpenClaw instances
Agent-to-agent communication — Trading agents, AI agents, autonomous systems talking over private networks
Private dashboards & APIs — HTTP endpoints accessible only to approved peers
Secure remote access — SSH, RDP, and other protocols over encrypted private networks

Quick Start

Prerequisites

Node.js 20+
Linux or macOS (Windows support planned)
Carrier identity (generate with agentnet init)

Installation

git clone https://github.com/0xli/decentlan.git
cd decentlan
npm install
npm run build

Basic Usage

On Machine A (provider):

# Initialize identity and config
agentnet init --name provider-macbook

# Start daemon
sudo agentnet up --name provider-macbook

On Machine B (partner):

agentnet init --name partner-openclaw
sudo agentnet up --name partner-openclaw

Grant access from A to B:

# Assign virtual IP
agentnet ipam assign --peer <B-carrier-id> --ip 10.86.12.34 --name partner-openclaw

# Grant access to SSH (port 22) for 1 hour
agentnet grant --peer <B-carrier-id> --tcp 22 --expires 1h

# Grant access to OpenClaw gateway (port 18789)
agentnet grant --peer <B-carrier-id> --tcp 18789 --expires 24h

Use the network:

# SSH to partner's machine
ssh partner@10.86.12.34

# Access OpenClaw gateway
curl http://10.86.12.34:18789/health

# Any other TCP service
# (HTTP, databases, custom APIs, etc.)

Revoke access:

agentnet revoke --peer <B-carrier-id>

Architecture

Your App / Agent → TUN Virtual Interface (10.86.x.x) 
                 → AgentNet Daemon (Routing, ACL, IPAM)
                 → Elastos Carrier (P2P Transport, Encryption, DHT, Relay)
                 → Remote Peer's AgentNet Daemon
                 → Remote TUN → Remote App / Agent

No modifications to the Carrier protocol. We build an application layer on top of Carrier's encrypted P2P foundation.

Key Features

Identity-based — Uses Carrier addresses (no central account system)
Private by default — Explicit access grants required (ACL deny-all)
Time-limited access — Support sessions can expire
Auditable — All connection attempts logged
NAT-friendly — Works behind any firewall (relies on Carrier's relay)
No public IP needed — Pure peer-to-peer over Carrier

Configuration

Main config is at ~/.agentnet/config.yaml:

node:
  name: my-machine
  namespace: agentnet-main

carrier:
  data_dir: ~/.carrier
  bootstrap_nodes:
    - bootstrap1.decent.network
    - bootstrap2.decent.network

network:
  interface: agentnet0
  ip: 10.86.1.10
  subnet: 10.86.0.0/16
  dns_domain: agentnet
  dns_port: 5353

Peer mappings are in ~/.agentnet/ipam.yaml:

peers:
  - name: partner-openclaw
    carrier_id: "8Rkxxx..."
    virtual_ip: 10.86.12.34
    services:
      - name: openclaw
        proto: tcp
        port: 18789
      - name: ssh
        proto: tcp
        port: 22

ACL rules are in ~/.agentnet/policy.yaml. Audit logs are in ~/.agentnet/audit.log.

Command Reference

Identity & Setup

agentnet init                          # Create ~/.agentnet, generate keys
agentnet identity show                 # Display Carrier ID, address, pubkey

Peer Management

agentnet peers list                    # List known peers and status
agentnet ipam assign                   # Register peer with virtual IP
  --peer <carrier-id>
  --ip <virtual-ip>
  --name <hostname>

agentnet resolve <hostname>            # Resolve name to virtual IP

Access Control

agentnet grant                         # Grant access to peer
  --peer <carrier-id>
  --tcp <port>                         # or --udp
  --expires <duration>                 # e.g., "1h", "24h", "7d"

agentnet revoke --peer <carrier-id>    # Revoke all access

agentnet audit log                     # View audit trail
  --tail <lines>
  --since <time>

Daemon Control

agentnet up                            # Start daemon
  --name <node-name>
  --ipam <namespace>

agentnet down                          # Stop daemon

agentnet status                        # Show daemon status

OpenClaw Integration

agentnet openclaw status --target <name>.agentnet
agentnet openclaw logs --target <name>.agentnet --follow
agentnet openclaw diagnose --target <name>.agentnet

How It Works

Carrier Friends — Two nodes must be Carrier friends (manually established using Carrier tooling).
Virtual Network — Each node runs a TUN interface (agentnet0) on the 10.86.0.0/16 subnet.
IP Mapping — IPAM maps Carrier IDs to virtual IPs (e.g., 8Rkxxx... → 10.86.12.34).
Packet Forwarding — When an app sends a packet to 10.86.12.34, the daemon:
- Intercepts it from the TUN interface
- Looks up the destination peer (Carrier ID)
- Checks the ACL (is access allowed?)
- Frames the packet and sends it via Carrier
- The remote daemon receives it and writes it to its TUN
Access Control — ACL rules control which peer can access which services/ports and for how long.
Audit Trail — All access attempts (allowed and denied) are logged.

Security Model

Encryption — All traffic is encrypted by Carrier (NaCl cryptography)
Authentication — Carrier public key is the identity; friend relationships are the trust boundary
Authorization — ACL rules grant explicit access; default is deny
Audit — Connection attempts are logged for compliance and debugging

Limitations (MVP v0.1)

Linux/macOS only (Windows in future)
TCP only (UDP planned in v0.2)
No remote desktop protocol support (TBD)
No video/media optimization (rely on Carrier relay)
Static IPAM (blockchain registry planned for v1.0)

Development

See CLAUDE.md for architecture, directory structure, and contributor guidelines.

Building from Source

npm install
npm run build
npm run typecheck      # Type-check without emitting
npm test              # Run tests
npm run dev           # Run in dev mode

Testing

npm test              # All tests
npm test -- --watch  # Watch mode
npm test -- --coverage  # Coverage report

Troubleshooting

TUN interface creation fails

If you get "Permission denied" when creating the TUN:

sudo agentnet up --name my-machine

The daemon needs CAP_NET_ADMIN to create the TUN interface.

Can't reach remote peer

Check both daemons are running: agentnet status
Verify you're Carrier friends: agentnet peers list
Check virtual IP is in IPAM: agentnet resolve <name>
Check ACL rules allow the port: agentnet audit log

Performance issues

Carrier relay can add latency. Direct P2P paths are ideal.
SSH is responsive even over relay.
For low-latency, ensure both nodes have good network connectivity.

Support & Feedback

GitHub Issues — https://github.com/0xli/decentlan/issues
Documentation — See docs/ directory
Discord — (link TBD)

License

MIT

References

Elastos Carrier — https://github.com/elastos/Elastos.NET.Carrier.Swift
Decent Network — https://github.com/0xli/decent-network
Tailscale — For VPN/LAN concepts
A2A Protocol — Agent-to-agent communication
MCP — Model Context Protocol for tool/AI integration

@decentnetwork/lan