High Level API

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


class txtorcon.Tor(reactor, control_protocol, _tor_config=None, _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:

The stable API provided by this class is txtorcon.interface.ITor

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.

get_config(*args, **kwargs)
Returns:a Deferred that fires with a TorConfig instance. This instance represents up-to-date configuration of the tor instance (even if another controller is connected). If you call this more than once you’ll get the same TorConfig back.
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.

is_ready(*args, **kwargs)
Returns:a Deferred that fires with True if this Tor is non-dormant and ready to go. This will return True if GETINFO dormant is false or if GETINFO status/enough-dir-info is true or if GETINFO status/circuit-established true.
become_ready(*args, **kwargs)

Make sure Tor is no longer dormant.

If Tor is currently dormant, it is woken up by doing a DNS request for torproject.org


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