Async-first • Type-safe • Tokio runtime

Tor control protocol
for Rust

A complete Rust implementation of the Tor control protocol. Connect to Tor, authenticate with any method, query network information, and subscribe to real-time events.

Documentation GitHub crates.io

tor_monitor.rs

use stem_rs::{Controller, Signal, EventType};

#[tokio::main]
async fn main() -> Result<(), stem_rs::Error> {
    // Connect to Tor control port
    let mut ctrl = Controller::from_port(
        "127.0.0.1:9051".parse()?
    ).await?;

    // Authenticate automatically
    ctrl.authenticate(None).await?;

    // Get Tor version
    let version = ctrl.get_version().await?;
    println!("Tor {}", version);

    // Subscribe to events
    ctrl.set_events(&[
        EventType::Bw,
        EventType::Circ,
    ]).await?;

    Ok(())
}

Capabilities

Everything you need to control Tor

A complete toolkit for building Tor-integrated applications with idiomatic Rust patterns and comprehensive type safety.

🔌

Control Socket

Connect to Tor via TCP or Unix domain sockets. Full async I/O with Tokio integration for high-performance applications.

TCP Unix Socket Async I/O

🔐

Authentication

All authentication methods with automatic detection. Secure credential handling with constant-time comparison.

SAFECOOKIE COOKIE PASSWORD

🎛️

Controller API

High-level interface for Tor interaction. Query configuration, send signals, manage circuits, and control hidden services.

Signals Circuits Config

📄

Descriptor Parsing

Complete parsing for all Tor descriptor types. Server, micro, consensus, extra-info, and hidden service descriptors.

Server Consensus Hidden Service

📡

Event Handling

Subscribe to real-time Tor events. Monitor bandwidth, circuit status, stream events, and log messages as they happen.

Bandwidth Circuits Streams

🚪

Exit Policy

Parse and evaluate exit policies. Determine what traffic a relay allows and make informed routing decisions.

Parse Evaluate Match

Quick Start

Up and running in minutes

Clear, well-documented examples to get you started with the most common use cases.

Connect & Authenticate

Establish connection to Tor control port

Rust

use stem_rs::{Controller, Error};

#[tokio::main]
async fn main() -> Result<(), Error> {
    // Connect to control port
    let mut ctrl = Controller::from_port(
        "127.0.0.1:9051".parse()?
    ).await?;
    
    // Auto-detect authentication method
    ctrl.authenticate(None).await?;
    
    println!("Connected to Tor!");
    Ok(())
}

Query Information

Get version, status, and network metrics

Rust

// Get Tor version
let version = ctrl.get_version().await?;
println!("Tor version: {}", version);

// Query traffic statistics
let bytes_read = ctrl.get_info("traffic/read").await?;
let bytes_written = ctrl.get_info("traffic/written").await?;

// Get active circuit status
let circuits = ctrl.get_info("circuit-status").await?;

Subscribe to Events

Real-time bandwidth and circuit monitoring

Rust

use stem_rs::EventType;

// Subscribe to bandwidth and circuit events
ctrl.set_events(&[
    EventType::Bw,
    EventType::Circ,
]).await?;

// Process events as they arrive
loop {
    let event = ctrl.recv_event().await?;
    println!("Event: {:?}", event);
}