Class
TorClient
Actor-isolated driver for a single embedded Tor instance.
actor TorClient
Mentioned In
Overview
TorClient is swift-tor’s primary entry point: one actor per Tor instance, strict Swift-concurrency isolation of all mutable state, and a high-level API that hides the dedicated tor_run_main() background thread, the embedded pre-authenticated control socket, and the AsyncStream fan-out of lifecycle events.
Basic usage
let client = TorClient(configuration: .ephemeral())
try await client.start()
try await client.waitUntilBootstrapped()
print("SOCKS reachable at \(await client.socksEndpoint!)")
let control = try await client.control()
let service = try await control.addOnion(
key: .newV3(discardPrivateKey: true),
ports: [.toLocalPort(80, localPort: 8080)]
)
await client.stop()
Thread model
Tor’s C entry point tor_run_main() is a blocking, single-threaded event loop that runs for the lifetime of the Tor instance. TorClient pins that loop to a dedicated Thread so the Swift concurrency runtime stays free for application work; actor isolation on every mutable property (state, socksEndpoint, the control client, the event-continuation map) serialises callers without blocking the Tor thread. Cross-thread bootstrapping happens through a CheckedContinuation in start().
Note
Conformance is Sendable via actor isolation; no @unchecked escape hatches. Pairs with TorSession for dependency injection (see TorSession for test-double guidance).
Important
A single TorClient owns its configuration.dataDirectory for the session. Constructing two clients pointed at the same data directory will fail the second one with TorError.startFailed(_:) due to Tor’s lockfile.
Topics
Creating
Lifecycle
Observing
Control access
Instance Methods
Relationships
Conforms To