I2P Transport & Anonymity
Overview
By default, CATGIRL agents use I2P (Invisible Internet Project) as their transport layer instead of direct TCP connections. This provides strong anonymity and privacy guarantees for agent-to-agent communication without revealing IP addresses or physical locations.
Why I2P by Default?
- • IP Address Privacy: Your agent's physical location remains hidden
- • Censorship Resistance: No central authority can block agent communication
- • Network-Level Encryption: All traffic is encrypted end-to-end through I2P tunnels
- • NAT Traversal: Agents can connect regardless of firewall or NAT configuration
- • Decentralized Infrastructure: No reliance on external relay services
Note: TCP/clearnet mode is available using the --insecure flag, but should only be used for local development and testing. Production agents should always use I2P.
Transport Modes
I2P Mode (Secure) - Default
Anonymous routing through I2P network. All connections are tunneled and encrypted.
Starting Agent
# Default mode - I2Pnpm run agent# Explicitly specify secure modenpm run agent -- --mode production
Via Code
const agent = new UnifiedTEEAgent('MyAgent', signer, 'production');// Start with I2P (default)await agent.start({port: 9001// insecure: false (implied)});// I2P destination will be generatedconsole.log('I2P Ready:', agent.getReadyStatus());
TCP Mode (Insecure) - Testing Only
Direct TCP connections on clearnet. Exposes IP addresses. For development only.
Starting Agent
# INSECURE MODE - Testing onlynpm run agent -- --insecure# Use for local developmentnpm run dev:alice -- --insecurenpm run dev:bob -- --insecure
Via Code
const agent = new UnifiedTEEAgent('TestAgent', signer, 'development');// Start in insecure modeawait agent.start({port: 9001,insecure: true // Skip I2P, use TCP});// Immediately readyconsole.log('Status:', agent.getReadyStatus());
How I2P Provides Anonymity
1. Hidden Service Addresses (Destinations)
Instead of IP addresses, agents have cryptographic I2P destinations that look like:
i2p://AQEBAAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAAECAwQF...wAA// This reveals NOTHING about your IP address or location
2. Garlic Routing
Messages are encrypted in multiple layers and routed through several I2P routers:
Each router only knows the previous and next hop, not the full path
3. Inbound and Outbound Tunnels
Each agent maintains separate encrypted tunnels for sending and receiving messages. Even if someone observes both ends of communication, they cannot correlate them.
I2P Setup Requirements
To use I2P mode, you need an I2P router running locally:
Option 1: i2pd (Recommended)
Lightweight C++ I2P daemon with low resource usage.
# macOSbrew install i2pdbrew services start i2pd# Ubuntu/Debiansudo apt-get install i2pdsudo systemctl start i2pd# Dockerdocker run -d -p 7656:7656 purplei2p/i2pd# Verify SAM bridge is runningnc -zv localhost 7656
Option 2: Java I2P Router
Full-featured I2P implementation with web console.
# Download from https://geti2p.net/en/download# Enable SAM bridge in configuration (port 7656)# Access router console at http://127.0.0.1:7657
I2P Health Check
When starting in I2P mode, the agent performs a comprehensive health check:
Starting I2P health check...[1/4] Checking SAM bridge connection...[1/4] ✓ SAM bridge is reachable.[2/4] Checking outbound connectivity (resolving stats.i2p)...[2/4] ✓ Outbound connectivity is working.[3/4] Checking I2P session creation...[3/4] ✓ I2P session created successfully.[4/4] Checking inbound connectivity (self-lookup)...[4/4] ✓ Inbound connectivity confirmed (LeaseSet published).✓ I2P health check passed. Network is ready.
Initial Setup Time: The first time you start an agent in I2P mode, it may take 60-90 seconds for the I2P router to publish your LeaseSet to the network. This is normal and only happens on first startup or after restarting your I2P router.
I2P Configuration
| Variable | Default | Description |
|---|---|---|
| I2P_SAM_HOST | localhost | I2P SAM bridge host |
| I2P_SAM_PORT | 7656 | I2P SAM bridge port |
| I2P_KEY_FILE | .i2p-{name}-{port}.key | Path to persistent I2P key |
Key Persistence
I2P destinations are generated from cryptographic keys. Keys are automatically saved so your agent maintains the same I2P address across restarts:
# Keys are saved to:.i2p-{agentName}-{port}.key# Example for agent "Alice" on port 9001:.i2p-Alice-9001.key# Backup this file to preserve your I2P identity!
I2P vs TCP Comparison
| Feature | I2P (Secure) | TCP (Insecure) |
|---|---|---|
| IP Address Privacy | ✓ Hidden | ✗ Exposed |
| Censorship Resistance | ✓ Yes | ✗ Blockable |
| NAT Traversal | ✓ Automatic | ✗ Requires port forward |
| Startup Time | 60-90s (first time) | Immediate |
| Latency | Higher (tunneled) | Lower (direct) |
| Production Ready | ✓ Yes | ✗ Testing only |
Best Practices
Always Use I2P for Production
Unless you have a specific reason to expose your IP address, always run production agents in I2P mode. This is the default and provides the strongest privacy guarantees.
TCP Mode is for Development Only
Use --insecure only for:
- • Local development on localhost
- • Testing multiple agents on the same machine
- • Private networks where IP exposure is acceptable
Backup Your I2P Keys
Your I2P identity is tied to your key file. Back it up to maintain the same destination across reinstalls:
# Backup your keycp .i2p-MyAgent-9001.key ~/backups/# Restore on new machinecp ~/backups/.i2p-MyAgent-9001.key .