negative zero

How to Use I2P

2021 February 8

[darknets] [i2p] [tech] [tutorial]

I wrote recently about the Invisible Internet Project (I2P), an anonymity darknet. I don't think it's obvious how to use I2P, so I wanted to write a post about it.

I'll assume in this guide that you're running GNU/Linux on the device running I2P (ideally a server) and a Firefox-based web browser on your client device (such as a laptop computer). If you're not, it shouldn't be a problem, but these steps may need to be amended a bit. I2P is written in Java, so it should run anywhere (that supports Java), and you'll access it via a proxy, which should be possible to set up in most web browsers.

Installing I2P

I2P works best when you keep it running all the time. For that reason, I recommend installing it on an always-on server if possible.

The official I2P client is written in Java. There's also a C++ client called i2pd. i2pd provides a basic I2P proxy but not all the features the official I2P client provides. This guide is specific to the Java implementation and references features and interfaces that are not available in i2pd.

Installing from Debian Packages

If you're running a Debian-based distro, see the official guide at (i2p | b32) for how to use the packages provided by the I2P project (to ensure you're up-to-date). Alternatively, you can install I2P from your distribution's packages.

Building from Source

If you want to install from source or use a precompiled binary, see (i2p | b32). I'll assume in this section that you're building from source. Follow the instructions in the INSTALL.txt file. Here's the basic process:

First, make sure you have the dependencies you need: Java SDK 8 or higher (such as OpenJDK), Apache Ant 1.9.8 or higher, and xgettext, msgfmt, and msgmerge from the GNU gettext package. On Fedora:

sudo dnf install java ant gettext

Next, build I2P from source with ant. When I was building it on my x86-64 Fedora desktop, the suggested command, ant pkg had errors. Instead, I compiled I2P successfully with:

ant installer-linux

This builds an installer jar. For me, this was called i2pinstall_0.9.48-0_linux-only.jar. Replace that name in the following commands with the name of your file.

Now, run this installer, either with the GUI:

java -jar i2pinstall_0.9.48-0_linux-only.jar

...or as console-only:

java -jar i2pinstall_0.9.48-0_linux-only.jar -console

Assuming all goes well, you'll have an executable called i2prouter. You can find the full instructions in INSTALL.txt for other commands, but to install I2P as a system service, run:

sudo sh i2prouter install

Now you can start and stop I2P using your init system (such as SystemD).

Connecting to I2P

Once I2P is up and running, we can access I2P through the web browser as a proxy.

Port Forwarding from Client to Server

This step assumes you're running I2P on one device (we'll call it the server) and the web browser on a different device (we'll call it the client). If you're running I2P on the same device as the web browser, skip this step.

The client needs to be able to establish an ssh connection to the server. Setting up ssh is beyond the scope of this post; I'll assume you already have it configured.

Run this command to use the server's I2P connection via the client:

ssh -L 4444:localhost:4444 -L 7657:localhost:7657 [username@]<server's IP address or hostname>[:port]

You may have set your ssh config file so you don't need to specify the username or port. Do what you need to do. For example, if your ssh config file specifies the username and port, your command may just look like this:

ssh -L 4444:localhost:4444 -L 7657:localhost:7657

This establishes an ssh connection to the server and forwards ports 4444 and 7657 to the server. While this connection is open, when we try to use port 4444 (used as the standard I2P HTTP proxy) or 7657 (used for the I2P Router Console), it will forward the request to the server. You can add additional ports to this command with the -L flag as needed.

(Note that the alternative i2pd client does not have an I2P Router Console on port 7657. If you're trying to use i2pd, you'll have trouble following guides like this one.)

Connecting to I2P in the Browser

At this point, you should be able to connect to the I2P HTTP proxy on port 4444 and to the I2P Router Console on port 7657. Regardless of your browser, the basic process to use I2P should be the same:

  1. To access eepsites (I2P sites), set your browser to use the HTTP proxy on port 4444.
  2. To access the I2P Router Console, go to localhost:7657 in your browser.

I'll walk through how to configure the HTTP proxy with Firefox-based browsers here.


  1. Go to about:preferences (the General section, which can be accessed by just clicking Preferences)
  2. Scroll down to the bottom to find Network Settings and click Settings...
  3. Under Configure Proxy Access to the Internet, set Manual proxy configuration with these settings:
    • HTTP Proxy: localhost, Port: 4444
    • Check the box that says "Also use this proxy for FTP and HTTPS"
    • Make sure the SOCKS Host entry is empty

To test this configuration, you can go to http://i2p-projekt.i2p, the I2P homepage. It may take a while after first starting I2P on the server before it's well-enough connected to find sites.

Tip: I recommend going into about:config and changing keyword.enabled to false. When this setting is set to true (the default), Firefox will assume you want to use your default search engine to search for anything that doesn't look like a URL. If you type an I2P address (such as i2p-projekt.i2p) into your URL bar without explicitly typing the http:// part, Firefox by default will try to search for that URL, rather than go to it. Turning off this setting will set the default behavior to try to visit the link rather than search for it.

Fingerprinting protection is beyond the scope of this post, but I recommend taking steps to minimize the uniqueness of your browser fingerprint. I strongly recommend disabling JavaScript.

Using Tor and I2P with Privoxy

Using the above instructions, your browser will be configured to use only I2P. The configured browser will only be used to access eepsites (with domains that end in .i2p). You may instead prefer to use I2P for eepsites and Tor for everything else. Caution: This may leak information. Using browsers other than the Tor Browser for Tor is strongly discouraged (onion) by the Tor Project, and the I2P project page warns that using Privoxy "could introduce leaks in your setup" (i2p | b32).

If you want to use Privoxy in this way despite that warning, first install Privoxy on the client. Then, modify the Privoxy config file (e.g., /etc/privoxy/config) by adding these lines:

forward-socks5t / .

forward .i2p

(Note that the first line ends with a period.)

Privoxy will use the last pattern matched to decide which proxy to use. So, by default, all traffic will be forwarded through a Tor-capable SOCKS5 proxy on port 9050, but .i2p sites will instead use the HTTP proxy on port 4444. Port 9050 is the default port for Tor to run as a service. Tor Browser runs its Tor proxy on port 9150. Change the ports as needed.

(This configuration will also allow you to access .onion sites.)

By default, Privoxy runs an HTTP proxy on port 8118. Assuming you haven't changed this port in your Privoxy config, run Privoxy, and then change your browser's HTTP proxy to port 8118 instead of 4444.

Congratulations, your browser should now be configured to use both Tor and I2P, as appropriate!

Configuring I2P


If you installed I2P using a Debian/Ubuntu package, you can configure some I2P settings, including how much RAM I2P is allowed to use, with

sudo dpkg-reconfigure i2p

I recommend doing this first.

Router Console

To access the I2P Router Console, go to localhost:7657 in your browser. The first time you access this, it should walk you through a setup wizard, which asks how much bandwidth to use for I2P. By default, you act as a relay on the I2P network, so please share what bandwidth you can to help out the network.

In this console, you can change many I2P settings. I'll highlight a few things you should do when setting up, but feel free to explore and change other settings as needed!

Firewall and Port Forwarding

I2P runs on a port that is randomly determined when you first run it (and stays the same after that). Go to localhost:7657/confignet and scroll down to "UDP Configuration" to find what your port is. (You can manually set it if you want, but you shouldn't need to.)

I2P will work best if you open this port on your firewall and enable port forwarding at your router. If you're able to do these things, please do. If you're unable, don't worry about it! I2P should still be able to operate; it just won't perform as well.

Limiting Tunnel Participation

I2P can use up a lot of CPU power. If you find that it's using too much, one way to limit CPU usage is by limiting the number of tunnels your I2P router can participate in. By default, this cannot be modified in the Router Console; you will need to manually modify the config file. Go to localhost:7657/configadvanced to see your router configuration. It will say under "Advanced I2P Configuration", "To make changes, edit the file: [path to file]". In my case, the file is stored at /var/lib/i2p/i2p-config/router.config. Go modify this file by adding the line:


Set the number to whatever you want. I found that unthrottled, my router participated in too many tunnels, and the performance of other programs on my server suffered because of it.


I found some things about I2P a bit hard to figure out. I hope this post is a good reference that explains how to get started, including key details that may not be obvious. Have fun with the Invisible Internet!