Framework

Tor

Swift-native, Sendable-first API for embedding the Tor anonymity network in macOS, iOS, and Linux applications.

Overview

Tor is the idiomatic Swift face of this package. It wraps a vendored build of Tor 0.4.8.21 behind Swift 6.1 structured concurrency so you can write async/await code against an embedded Tor instance on macOS 15+, iOS 18+, and Linux (Ubuntu 22.04+). The package depends on swift-event (libevent) and swift-openssl (libcrypto/libssl) for its native stack, and surfaces a small, typed API with no raw OpaquePointer leakage.

Direct-use capabilities shipping today span five areas.

Actor-isolated Tor driver — construct, start, wait for bootstrap, inspect, stop. See TorClient.

Typed control protocol — GETINFO, SETCONF, SETEVENTS, ADD_ONION, SIGNAL through an async client. See TorControlClient.

v3 onion-service lifecycle — register, re-adopt, and delete ephemeral .onion services. See OnionService, OnionKeySpec, OnionPortMapping.

Event stream — back-pressure-aware AsyncStream of bootstrap progress, circuit/stream status, and log messages. See TorEvent, TorSession.

Apple-only URLSession wiring — one-step URLSession over SOCKS5 proxy. See URLSessionConfiguration.configuredForTor(socksEndpoint:) and makeURLSession(ephemeral:).

import Tor

let client = TorClient(configuration: .ephemeral())
try await client.start()
try await client.waitUntilBootstrapped()
print("SOCKS5 reachable at \(await client.socksEndpoint!)")
await client.stop()

Concurrency and security

Every type in the public surface is Sendable — TorClient is an actor, TorControlClient and ControlSocket use Mutex<State> from the Synchronization module (SE-0410), and value types carry all their state structurally. No @unchecked Sendable escape hatches remain in the call graph, which is why the platform floor is iOS 18 / macOS 15.

Onion-service private keys are surfaced through privateKey as plain String? blobs. Treat them as credentials: persist only via Keychain on Apple platforms (or an equivalent credential store on Linux), and never log them.

API positioning

Tor is a thin, tor_api-direct async/await wrapper. It is not a replacement for Arti — if you need Rust’s memory-safety guarantees end-to-end, or anonymity features Arti has already shipped and the C Tor has not, reach for Arti. Reach for Tor when you want the stability of the reference C implementation, direct access to the full control-protocol vocabulary, or tight integration with Swift’s structured concurrency.

Topics

Essentials

Control protocol

Using the Tor Control Protocol
Learn to interact with an embedded Tor instance via TorControlClient — the typed async client that wraps Tor’s control protocol (control-spec.txt) for state introspection, configuration mutation, event subscription, signal dispatch, and the v3 onion-service lifecycle.
class TorControlClient
Sendable high-level client for Tor’s control protocol (control-spec.txt).
class ControlSocket
Cross-platform, Sendable line-oriented wrapper around a Tor control socket file descriptor.
struct ControlReply
A fully-parsed Tor control-protocol reply, ready for business logic.
enum ControlProtocolParser
Namespace enum holding all stateless control-protocol parsing routines.

Onion services

Events and state

Values

Errors

enum TorError
Canonical error surface for every swift-tor failure mode.

Apple-only

func makeURLSession(ephemeral: Bool) async throws -> URLSession
Return a ready-to-use URLSession that routes every request through this Tor instance’s SOCKS5 proxy.