High Level API

This is the recommended API. See the Programming Guide for “prose” documentation of these (and other) APIs.


class txtorcon.Tor(reactor, tor_config, _process_proto=None)

Bases: object

I represent a single instance of Tor and act as a Builder/Factory for several useful objects you will probably want. There are two ways to create a Tor instance:

If you desire more control, there are “lower level” APIs which are the very ones used by this class. However, this “highest level” API should cover many use-cases:

import txtorcon

def main(reactor):
    # tor = yield txtorcon.connect(UNIXClientEndpoint(reactor, "/var/run/tor/control"))
    tor = yield txtorcon.launch(reactor)

    onion_ep = tor.create_onion_endpoint(port=80)
    port = yield onion_ep.listen(Site())

don’t instantiate this class yourself – instead use the factory methods txtorcon.launch() or txtorcon.connect()

quit(*args, **kwargs)

Closes the control connection, and if we launched this Tor instance we’ll send it a TERM and wait until it exits.


The TorControlProtocol instance that is communicating with this Tor instance.


The TorConfig instance associated with the tor instance we launched. This instance represents up-to-date configuration of the tor instance (even if another controller is connected).

web_agent(pool=None, _socks_endpoint=None)
  • _socks_endpoint – If None (the default), a suitable SOCKS port is chosen from our config (or added). If supplied, should be a Deferred which fires an IStreamClientEndpoint (e.g. the return-value from txtorcon.TorConfig.socks_endpoint()) or an immediate IStreamClientEndpoint You probably don’t need to mess with this.
  • pool – passed on to the Agent (as pool=)
dns_resolve(*args, **kwargs)
Parameters:hostname – a string
Returns:a Deferred that calbacks with the hostname as looked-up via Tor (or errback). This uses Tor’s custom extension to the SOCKS5 protocol.
dns_resolve_ptr(*args, **kwargs)
Parameters:ip – a string, like “”
Returns:a Deferred that calbacks with the IP address as looked-up via Tor (or errback). This uses Tor’s custom extension to the SOCKS5 protocol.
stream_via(host, port, tls=False, _socks_endpoint=None)

This returns an IStreamClientEndpoint instance that will use this Tor (via SOCKS) to visit the (host, port) indicated.

  • host – The host to connect to. You MUST pass host-names to this. If you absolutely know that you’ve not leaked DNS (e.g. you save IPs in your app’s configuration or similar) then you can pass an IP.
  • port – Port to connect to.
  • tls – If True, it will wrap the return endpoint in one that does TLS (default: False).
  • _socks_endpoint – Normally not needed (default: None) but you can pass an IStreamClientEndpoint_ directed at one of the local Tor’s SOCKS5 ports (e.g. created with txtorcon.TorConfig.create_socks_endpoint()). Can be a Deferred.
create_state(*args, **kwargs)

returns a Deferred that fires with a ready-to-go txtorcon.TorState instance.


# FIXME why doesn’t “txtorcon.connect” work here with automethod??