go-i2p
A pure Go implementation of the I2P router.
Status
go-i2p is in active development. We recently completed several significant milestones including:
- Complete I2CP Protocol Server: Full session lifecycle management, message routing, and client support
- End-to-End Message Routing: Complete message routing system connecting I2CP clients through tunnels to other destinations with garlic encryption
- Tunnel System: Automatic tunnel building, pool management, and cryptographic processing
- Transport Layer: Full NTCP2 implementation with session management
go-i2p is still in very early development. It has bugs. It is probably very distinct on the network. You probably should use a more established router for now.
Advice for Developers: The API is still unstable below go-i2p/onramp. In fact, we're going to aggressively remove broken, crappy versions of functions from the low-level components over the 0.1.6 to 0.2.0 development cycle. The 0.2.0 release will have only the type-safe, memory-safe, functionally-correct versions of everything. We'll apply DEPRECATED notices to the godoc of anything we're removing in advance of removing it but it is going to go. How much low-level stuff you want to use is going to affect how much your life is going to change in the next ~4 big releases.
Also, we're picking up the pace. More little points between big releases. This is because issues surfaced in one repository may actually require fixes in an upstream repo and this way it's easier to keep the tags in sync.
Advice for Users: It's probably not safe yet, nor does it do the things you want yet. However, we have reached significant milestones in interacting with the network and are beginning to use it more regularly in a handful of non-anonymous services.
Anonymity-sensitive operators should review Anonymity-Safe Logging and avoid debug logging in production.
Implemented Features
- Clients
- End-to-End Crypto (crypto engine in go-noise/ratchet)
lib/i2np/garlic_session.go → go-noise/ratchet.SessionManager)
- [X] ECIES-X25519-AEAD-Ratchet (primary, implemented in go-noise/ratchet/)
- [X] Tunnel build record crypto (adapter in lib/i2np/build_record_crypto_short.go → github.com/go-i2p/crypto/tunnel)
- [ ] ElGamal/AES+SessionTag (not implemented - ECIES-only destinations supported)
- I2NP
- NetDB
- Transport Layer
--transport.ssu2-enabled help text)
- [X] Session handshake
- [X] Connection management
- [X] Peer Tests (experimental — all roles implemented; end-to-end integration ongoing)
- [X] Introducers (experimental — registration and republish wired)
- Noise Subsystem (see also https://github.com/go-i2p/go-noise)
- [X] Noise Socket Framework
- [X] NTCP2 Socket Framework
- [X] ECIES-X25519-AEAD-Ratchet engine (ratchet/ package)
- [X] SSU2 Socket Framework
- Tunnels
Verbosity
Logging can be enabled and configured using the DEBUG_I2P environment variable. By default, logging is disabled.
Note: Logging is configured via environment variables (not config.yaml or command-line flags) because it is managed by an external logger package and needs to be set before the application starts.
There are four available log levels:
- Debug (very high volume — hot-path / crypto detail; local troubleshooting only)
export DEBUG_I2P=debug- Info (lifecycle and operational milestones; recommended default for
./run.shand day-to-day runs)
export DEBUG_I2P=info- Warn
export DEBUG_I2P=warn- Error
export DEBUG_I2P=errorIf DEBUG_I2P is set to an unrecognized value, go-i2p falls back to info.
Fast-Fail mode
Fast-Fail mode can be activated by setting WARNFAIL_I2P to any non-empty value. When set, every warning or error is Fatal.
It is unsafe for production use, and intended only for debugging and testing purposes.
export WARNFAIL_I2P=trueIf WARNFAIL_I2P is set and DEBUG_I2P is unset, DEBUG_I2P will be set to debug.
I2CP Server
The I2CP (I2P Client Protocol) server allows client applications to communicate with the I2P router. It is enabled by default and listens on localhost:7654.
Configuration
You can configure the I2CP server using command-line flags:
# Disable I2CP server
go-i2p --i2cp.enabled=false
Change listen address
go-i2p --i2cp.address=0.0.0.0:7654
Adjust maximum sessions (default is 100)
go-i2p --i2cp.max-sessions=200
Valid range for i2cp.max-sessions is 1-320
Use Unix domain socket instead of TCP
go-i2p --i2cp.network=unix --i2cp.address=/tmp/i2cp.sockFeatures
- Session Management: Create, reconfigure, and destroy client sessions
- Message Protocol: Full I2CP v0.9.67 protocol implementation
- Multi-client Support: Handle multiple concurrent client sessions (default: 100)
- Thread-safe: Concurrent session access with proper synchronization
Note: messageReliability=Guaranteed is not yet implemented. Sessions
requesting guaranteed delivery fall back to BestEffort silently. Applications
requiring acknowledgment must implement their own delivery-confirmation layer
(e.g., via the go-streaming library).
For more details, see lib/i2cp/README.md.
Contributing
See CONTRIBUTING.md for more information.
License
This project is licensed under the MIT license, see LICENSE for more information.