Router configuration

emissary-cli can be configured via either command-line arguments or a configuration file (router.toml). Modifying router.toml is just a way of passing command line arguments to the router at boot. For example, running emissary-cli with --allow-local and setting option allow_local = true in the config file will have the same effect.

Options specified on the command line take precedence over those in the config file.

Example router.toml:

allow_local = false
floodfill = false
insecure_tunnels = false

[http-proxy]
port = 4444
host = "127.0.0.1"

# upnp enabled, nat-pmp disabled
[port-forwarding]
upnp = true
nat_pmp = false
name = "emissary"

# ipv4 and ipv6 hosts not specified
# upnp is used to resolve external address
[ntcp2]
port = 25515
publish_ipv4 = true
publish_ipv6 = true

# i2cp disabled
# [i2cp]
# port = 7654

[sam]
tcp_port = 7656
udp_port = 7655

Available options

Run emissary-cli --help to show the built-in help message with all available options.

General options

Config file	CLI	Description
-	-b, --base-path <PATH>	Path where router files are stored. (default: ~/.emissary)
log	-l, --log <LOG>	Logging targets. By default, INFO is enabled for all logging targets
floodfill	--floodfill	Run the router as a floodfill. (default: false)
insecure_tunnels	--insecure-tunnels	Allow insecure tunnels. Disables /16 subnet and maximum tunnel participation checks. Should only be used for testing. (default: false)
caps	--caps <CAPS>	Router capabilities, not useful outside of testing
net_id	--net-id <NET-ID>	Network ID the router belongs to (default: 2)
-	--ovewrite-config	Overwrite existing configuration file with defaults.

NTCP2

Config file section: [ntcp2]

Config file	CLI	Description
ipv4	-	Enable IPv4 (default: true)
ipv4_host	-	Public IPv4 address for incoming connections. Can be auto-discovered via SSU2/UPnP/NAT-PMP if left empty.
ipv6	-	Enable IPv6 (default: true)
ipv6_host	-	Public IPv6 address for incoming connections. Can be auto-discovered via SSU2 if left empty.
port	-	Port to listen for incoming NTCP2 connections. (default: random port between 9151-30777)
publish_ipv4	-	Publish the IPv4 address in router info for incoming connections. (default: true)
publish_ipv6	-	Publish the IPv6 address in router info for incoming connections. (default: true)
disable_pq	-	Disable PQ connections (default: false)
ml_kem	-	ML-KEM preference for inbound connections (default: 4)

ML-KEM preference (ml_kem)

ml_kem allows specifying an ML-KEM variant used for inbound connections. If ml_kem is not specified in [ntcp2], the router will only accept x25519 connections.

Number	Protocol
3	ML-KEM-512
4	ML-KEM-768
5	ML-KEM-1024

Example:

[ntcp2]
port = 25515
ipv4_host = "203.0.113.50"
publish_ipv4 = true
publish_ipv6 = false
ipv4 = true
ipv6 = true

# use ml-kem-512 for inbound connections
ml_kem = 3

SSU2

Config file section: [ssu2]

Config file	CLI	Description
ipv4	-	Enable IPv4 (default: true)
ipv4_host	-	Public IPv4 address for incoming connections. Can be auto-discovered via SSU2/UPnP/NAT-PMP if left empty.
ipv4_mtu	-	IPv4 MTU (default: 1500)
ipv6	-	Enable IPv6 (default: true)
ipv6_host	-	Public IPv6 address for incoming connections. Can be auto-discovered via SSU2 if left empty.
ipv6_mtu	-	IPv6 MTU (default: 1500)
port	-	Port to listen for incoming SSU2 connections. (default: random port between 9151-30777)
publish_ipv4	-	Publish the IPv4 address in router info for incoming connections. (default: true)
publish_ipv6	-	Publish the IPv6 address in router info for incoming connections. (default: true)
disable_pq	-	Disable PQ connections (default: false)
ml_kem	-	ML-KEM preferences for inbound connections (default: 4,3)

ML-KEM preference (ml_kem)

ml_kem allows specifying ML-KEM variants used for inbound connections. If ml_kem is not specified in [ssu2], the router will only accept x25519 connections. If two numbers are given, the order specifies preference.

Number	Protocol
3	ML-KEM-512 only
3,4	ML-KEM-512, ML-KEM-768
4	ML-KEM-768
4,3	ML-KEM-768, ML-KEM-512

Example:

[ssu2]
port = 25515
ipv4 = false
ipv6_mtu = 1300
publish_ipv6 = true

# use ml-kem-512, ml-kem-768
ml_kem = "3,4"

Bandwidth

Config file section: [bandwidth]

Config file	CLI	Description
bandwidth	--bandwidth	Bandwidth limit in bytes (default: 1000000)
share_ratio	--share-ratio	How much of bandwdith can be allocated for transit traffic (default: 90%)

Example:

[bandwidth]
bandwidth = 5000000 # 5 MB/s

# only 50% allocated for transit (2.5 MB/s)
share_ratio = 0.5

HTTP proxy

Config file section: [http-proxy]

Config file	CLI	Description
port	--http-proxy-port	HTTP proxy port. (default: 4444)
host	--http-proxy-host	HTTP proxy bind address. (default: 127.0.0.1)
outproxy	--http-outproxy	HTTP outproxy
inbound_len	-	Length of inbound tunnels. (default: 3)
inbound_count	-	Number of inbound tunnels. (default: 2)
outbound_len	-	Length of outbound tunnels. (default: 3)
outbound_count	-	Number of outbound tunnels. (default: 2)
i2cp.leaseSetEncType	-	Encryption type (default: 6,4)

Example:

[http-proxy]
port = 4444
host = "127.0.0.1"
outproxy = "http://exit.stormycloud.i2p"

# outproxy also accepts an optional port
# outproxy = "http://outproxy.i2p:1337"

# use x25519 only
i2cp.leaseSetEncType = "4"

# optional
inbound_len = 3
inbound_count = 2
outbound_len = 3
outbound_count = 2

INFO

HTTP proxy requires SAM to be enabled.

SOCKS proxy

Config file section: [socks-proxy]

Config file	CLI	Description
port	--socks-proxy-port <PORT>	SOCKS proxy port. (default: 4447)
host	--socks-proxy-host <HOST>	SOCKS proxy bind address. (default: 127.0.0.1)
outproxy	--socks-outproxy <HOST>	SOCKS outproxy
i2cp.leaseSetEncType	-	Encryption type (default: 6,4)

Example:

[socks-proxy]
port = 4447
host = "127.0.0.1"
outproxy = "127.0.0.1:9050"

INFO

SOCKS proxy requires SAM to be enabled.

SAMv3

Config file section: [sam]

Config file	CLI	Description
tcp_port	-	SAM TCP port. (default: 7656)
udp_port	-	SAM UDP port for datagrams. (default: 7655)
host	-	SAM bind address. (default: 127.0.0.1)

Example:

[sam]
tcp_port = 7656
udp_port = 7655
host = "127.0.0.1"

I2CP

Config file section: [i2cp]

Config file	CLI	Description
port	-	I2CP port. (default: 7654)
host	-	I2CP bind address. (default: 127.0.0.1)

Example:

[i2cp]
port = 7654
host = "127.0.0.1"

Address book

Config file section: [address-book]

Config file	CLI	Description
default	-	Default address book subscription URL for initial bootstrap.
subscriptions	-	List of additional address book subscription URLs.

Example:

[address-book]
default = "http://udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p/hosts.txt"
subscriptions = ["http://your-favorite-address-service.i2p/hosts.txt"]

INFO

Address book requires SAM to be enabled. If disabled, .i2p host lookups are not supported and all connections must use .b32.i2p addresses.

Exploratory tunnels

Config file section: [exploratory]

Config file	CLI	Description
inbound_len	--exploratory-inbound-len <NUM>	Length of inbound exploratory tunnels.
inbound_count	--exploratory-inbound-count <NUM>	Number of inbound exploratory tunnels.
outbound_len	--exploratory-outbound-len <NUM>	Length of outbound exploratory tunnels.
outbound_count	--exploratory-outbound-count <NUM>	Number of outbound exploratory tunnels.

Example:

[exploratory]
inbound_len = 2
inbound_count = 3
outbound_len = 2
outbound_count = 3

Transit tunnels

Transit tunnels allow your router to participate in the I2P network by relaying traffic for other routers.

Config file section: [transit]

Config file	CLI	Description
max_tunnels	--max-transit-tunnels <NUM>	Maximum number of transit tunnels. (default: 1000)
-	--disable-transit-tunnels	Disable transit tunnel participation entirely. Router will publish G caps.

Example:

[transit]
max_tunnels = 10_000

INFO

Disabling transit means the router is started with G caps, i.e., "rejecting all tunnels" and all inbound tunnel build requests are rejected.

Port forwarding (UPnP/NAT-PMP)

Automatic port forwarding and external address discovery.

Config file section: [port-forwarding]

Config file	CLI	Description
upnp = true	-	Enable UPnP. (default: true)
nat_pmp = true	-	Enable NAT-PMP. (default: true)
name	--upnp-name <NAME>
upnp = false	--disable-upnp	Disable UPnP via CLI.
nat_pmp = false	--disable-nat-pmp	Disable NAT-PMP via CLI.

Example:

[port-forwarding]
name = "emissary"
nat_pmp = true
upnp = false

INFO

NAT-PMP is tried first and if it's not available, UPnP is used as a fallback. If neither protocol is available, ports must be forwarded manually.

Reseeding

Config file section: [reseed]

Config file	CLI	Description
hosts	--reseed-hosts <HOST>,...	Comma-separated list of reseed host URLs.
reseed_threshold	--reseed-threshold <NUM>	Minimum number of known routers before requesting reseed. (default: 25)
-	--disable-reseed	Don't reseed even if there aren't enough routers.
-	--force-reseed	Forcibly reseed even if there are enough routers.
-	--disable-force-ipv4	Disable forcing IPv4 when connecting to reseed hosts.

Example:

[reseed]
reseed_threshold = 25
hosts = ["https://specific-reseed-host.com/"]

Metrics

Prometheus-compatible metrics server.

See the debugging guide for more information on metrics.

Config file section: [metrics]

Config file	CLI	Description
port	--metrics-server-port <PORT>	Metrics server port. (default: 7788)
-	--disable-metrics	Disable metrics server

Example:

[metrics]
port = 7788

Client tunnels

Client tunnels forward local ports to remote I2P destinations.

Config file section: [[client-tunnels]]

Config file	Description
name	Unique name for the tunnel.
address	Local bind address.
port	Local port to listen on.
destination	Remote I2P destination (.i2p or .b32.i2p).
destination_port	Remote destination port.

Client tunnels share the same destination and tunnel pool and they can be configured with [client-tunnel-options]

Config file	Description
i2cp.leaseSetEncType	Encryption type (default: 6,4)

Example:

[client-tunnel-options]
# use ml-kem-768 only
i2cp.leaseSetEncType = "6"

[[client-tunnels]]
name = "irc"
address = "127.0.0.1"
port = 6668
destination = "irc.postman.i2p"
destination_port = 6667

INFO

Client tunnels require SAM to be enabled. Each tunnel must have a unique name and port.

Server tunnels

Server tunnels expose local services to the I2P network.

Config file section: [[server-tunnels]]

Config file	Description
name	Unique name for the tunnel.
port	Local port where the service is running.
destination_path	Path to the destination keys file.
i2cp.leaseSetEncType	Encryption type (default: 6,4)

Example:

[[server-tunnels]]
name = "my-website"
port = 8080
destination_path = "/path/to/base64-destination.keys"

INFO

Server tunnels require SAM to be enabled. Each tunnel must have a unique name, port, and destination path.

Router UI

Config file section: [router-ui]

Config file	CLI	Description
-	--disable-ui	Disable router UI
native	--native	Use native UI (default: false)
theme	--theme	Options: light, dark (Default: dark)
refresh_interval	--refresh-interval	How often the UI should update. (default: 5)
port	--web-ui-port	The port to start the webserver on. (default: 7657)

Example:

[router-ui]
theme = "dark"
port = 7657

# update UI once a second
refresh_interval = 1

Enabling and disabling subsystems

To disable a subsystem, remove or comment out its section in router.toml. To re-enable it, uncomment the section and restart the router.

For most subsystems (I2CP, SAM, transports), disabling them means the service is not started and routers/applications cannot connect to those endpoints.

Examples

Transit tunnels disabled, address book enabled:

# [transit]
# max_tunnels = 10000

[address-book]
default = "http://udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p/hosts.txt"
subscriptions = ["http://your-favorite-address-service.i2p/hosts.txt"]

Address book, SAM and HTTP proxy disabled, I2CP enabled:

# [address-book]
# default = "http://udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p/hosts.txt"
# subscriptions = []

# [http-proxy]
# port = 4444
# host = "127.0.0.1"

# [sam]
# tcp_port = 7656
# udp_port = 7655

[i2cp]
port = 7654

SAM and address book enabled but no hosts.txt downloaded:

[address-book]
# default = "http://udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p/hosts.txt"
# subscriptions = []

[sam]
tcp_port = 7656
udp_port = 7655