How to Configure Proxy, Tor, and I2P Settings in Maigret for Privacy

You can route Maigret's network requests through Tor, I2P, or standard HTTP/SOCKS proxies by setting the --tor-proxy, --i2p-proxy, or --proxy CLI flags, or by defining tor_proxy_url, i2p_proxy_url, and proxy_url in your settings.json file.

Maigret uses aiohttp for all HTTP requests, enabling you to tunnel traffic through privacy networks to shield your originating IP address from target services. The soxoj/maigret repository implements a three-layer configuration system that allows you to define proxy settings persistently in JSON, override them via command-line arguments, or specify them through the web interface.

Proxy Configuration Architecture in Maigret

The proxy configuration flows through three distinct layers before reaching the network layer:

1. Persistent Configuration – maigret/resources/settings.json stores default values for tor_proxy_url (socks5://127.0.0.1:9050), i2p_proxy_url (http://127.0.0.1:4444), and proxy_url (null). The Settings.load() method in maigret/settings.py reads these values at startup, checking ~/.maigret/settings.json for user overrides.

2. Command-Line Override – The argument parser in maigret/maigret.py defines --tor-proxy, --i2p-proxy, and --proxy flags that supersede JSON defaults. These values populate the args namespace and propagate through the execution chain.

3. Runtime Connector Creation – Both maigret/submit.py and maigret/checking.py instantiate ProxyConnector.from_url(proxy) from the aiohttp-socks package when a proxy URL is provided, creating an encrypted tunnel for all aiohttp ClientSession requests.

Configuring Tor Proxy in Maigret

To route requests through the Tor network, ensure your local Tor gateway is running (typically on port 9050) and configure Maigret to use the SOCKS5 proxy.

Using the Command Line Interface

Pass the --tor-proxy flag with your local Tor SOCKS5 endpoint:

maigret username \
    --tor-proxy socks5://127.0.0.1:9050

This overrides any default settings and forces all username lookups through the Tor circuit.

Persisting Settings in JSON Configuration

Create or edit ~/.maigret/settings.json to permanently enable Tor routing:

{
    "proxy_url": null,
    "tor_proxy_url": "socks5://127.0.0.1:9050",
    "i2p_proxy_url": "http://127.0.0.1:4444"
}

Maigret automatically loads this file on startup via Settings.load(), applying the Tor proxy to every request without requiring CLI flags.

Web UI Configuration

When using the Flask-based web interface (maigret/web/app.py), enter your Tor proxy URL in the tor_proxy form field. The POST handler passes this value directly to the backend checking logic, identical to CLI behavior.

Configuring I2P Proxy for Anonymous Requests

I2P operates as an HTTP proxy rather than SOCKS5. Configure Maigret to use the local I2P gateway endpoint.

CLI Configuration for I2P

Specify the --i2p-proxy flag with the HTTP address of your I2P router:

maigret username \
    --i2p-proxy http://127.0.0.1:4444

JSON Configuration for I2P

Update your persistent settings in ~/.maigret/settings.json:

{
    "proxy_url": null,
    "tor_proxy_url": null,
    "i2p_proxy_url": "http://127.0.0.1:4444"
}

The i2p_proxy_url value in maigret/resources/settings.json defaults to http://127.0.0.1:4444, matching the standard I2P HTTP proxy port.

Generic HTTP/HTTPS Proxy Support

For standard VPN or corporate proxies, use the --proxy flag supporting both HTTP and SOCKS protocols:

maigret username \
    --proxy http://user:pass@proxy.example.com:8080

Set --proxy "" to explicitly disable any proxy configured in your JSON settings.

Technical Implementation Details

Maigret's proxy implementation relies on the aiohttp-socks library to extend aiohttp's networking capabilities. In maigret/submit.py, the Submitter class constructs sessions using conditional connector logic:

from aiohttp_socks import ProxyConnector

if proxy:
    connector = ProxyConnector.from_url(proxy)
else:
    connector = aiohttp.TCPConnector(ssl=ssl_context)
    
session = aiohttp.ClientSession(
    connector=connector,
    trust_env=True,
    cookie_jar=cookie_jar
)

The same pattern appears in maigret/checking.py, where the core request function receives proxy, tor_proxy, and i2p_proxy arguments and selects the appropriate connector. This ensures that whether you use the --submit mode, standard checking, or the web UI, all traffic routes through your specified privacy network.

Summary

• Maigret supports Tor via SOCKS5 (socks5://127.0.0.1:9050), I2P via HTTP (http://127.0.0.1:4444), and standard HTTP/SOCKS proxies.
• Configure proxies persistently in ~/.maigret/settings.json using keys tor_proxy_url, i2p_proxy_url, and proxy_url.
• Override JSON settings at runtime with --tor-proxy, --i2p-proxy, and --proxy CLI arguments defined in maigret/maigret.py.
• The ProxyConnector.from_url() method in maigret/submit.py and maigret/checking.py handles the actual network routing via aiohttp-socks.
• Web UI users can specify proxies through form fields that mirror CLI functionality in maigret/web/app.py.

Frequently Asked Questions

Can I use both Tor and a standard proxy simultaneously in Maigret?

No, Maigret accepts multiple proxy arguments, but only one proxy URL is applied per request session. The code in maigret/submit.py creates a single ProxyConnector instance from the first available proxy in the priority order: explicit --proxy flag, then --tor-proxy, then --i2p-proxy. You cannot chain proxies for additional layering within a single Maigret invocation.

Why does Maigret use SOCKS5 for Tor but HTTP for I2P?

Tor operates a SOCKS5 proxy interface (typically port 9050) that can handle any TCP connection type, making it compatible with the ProxyConnector class from aiohttp-socks. I2P, however, exposes an HTTP proxy interface (port 4444) designed specifically for web traffic. Maigret's default values in maigret/resources/settings.json reflect these protocol standards: socks5://127.0.0.1:9050 for Tor and http://127.0.0.1:4444 for I2P.

Do I need to install additional dependencies for proxy support?

Yes, Maigret requires the aiohttp-socks package to create ProxyConnector instances. While basic Maigret functionality works with standard aiohttp, attempting to use --tor-proxy or --proxy without aiohttp-socks installed will raise an import error when maigret/submit.py or maigret/checking.py attempts to instantiate the connector class.

How do I verify that Maigret is actually using my Tor proxy?

Check your Tor logs for connection attempts when running Maigret, or use a test username known to trigger specific IP-based responses. Since Maigret uses trust_env=True in its ClientSession configuration, ensure no environment variables like http_proxy override your explicit settings. The proxy URL applied is passed directly to ProxyConnector.from_url(), confirming the connection routes through your specified SOCKS5 endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}