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 [email protected]

# 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

1. Carrier Friends — Two nodes must be Carrier friends (manually established using Carrier tooling).

2. Virtual Network — Each node runs a TUN interface (agentnet0) on the 10.86.0.0/16 subnet.

3. IP Mapping — IPAM maps Carrier IDs to virtual IPs (e.g., 8Rkxxx... → 10.86.12.34).

4. 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

5. Access Control — ACL rules control which peer can access which services/ports and for how long.

6. 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

1. Check both daemons are running: agentnet status
2. Verify you're Carrier friends: agentnet peers list
3. Check virtual IP is in IPAM: agentnet resolve <name>
4. 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