<!--
{
  "availability" : [

  ],
  "documentType" : "symbol",
  "framework" : "Tor",
  "identifier" : "/documentation/Tor",
  "metadataVersion" : "0.1.0",
  "role" : "Framework",
  "symbol" : {
    "kind" : "Framework",
    "modules" : [
      "Tor"
    ],
    "preciseIdentifier" : "Tor"
  },
  "title" : "Tor"
}
-->

# 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](https://gitlab.torproject.org/tpo/core/tor) 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`](https://github.com/21-DOT-DEV/swift-event) (libevent) and [`swift-openssl`](https://github.com/21-DOT-DEV/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`](/documentation/Tor/TorClient).

**Typed control protocol** — `GETINFO`, `SETCONF`, `SETEVENTS`, `ADD_ONION`, `SIGNAL` through an `async` client. See [`TorControlClient`](/documentation/Tor/TorControlClient).

**v3 onion-service lifecycle** — register, re-adopt, and delete ephemeral `.onion` services. See [`OnionService`](/documentation/Tor/OnionService), [`OnionKeySpec`](/documentation/Tor/OnionKeySpec), [`OnionPortMapping`](/documentation/Tor/OnionPortMapping).

**Event stream** — back-pressure-aware `AsyncStream` of bootstrap progress, circuit/stream status, and log messages. See [`TorEvent`](/documentation/Tor/TorEvent), [`TorSession`](/documentation/Tor/TorSession).

**Apple-only URLSession wiring** — one-step `URLSession` over SOCKS5 proxy. See `URLSessionConfiguration.configuredForTor(socksEndpoint:)` and [`makeURLSession(ephemeral:)`](/documentation/Tor/TorClient/makeURLSession(ephemeral:)).

```swift
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`](/documentation/Tor/TorClient) is an `actor`, [`TorControlClient`](/documentation/Tor/TorControlClient) and [`ControlSocket`](/documentation/Tor/ControlSocket) use `Mutex<State>` from the [`Synchronization` module (SE-0410)](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0410-atomics.md), 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`](/documentation/Tor/OnionService/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](https://gitlab.torproject.org/tpo/core/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

[Getting Started with swift-tor](/documentation/Tor/GettingStarted)

A task-oriented walkthrough of swift-tor: add the dependency, start an embedded Tor instance, route SOCKS5 traffic, publish a v3 onion service, and shut down cleanly.

[Production Considerations](/documentation/Tor/ProductionConsiderations)

Pre-1.0 caveats, threat-model boundaries, key-handling discipline, log hygiene, bootstrap performance, concurrency model, and platform exclusions for swift-tor in production deployments.

[`TorClient`](/documentation/Tor/TorClient)

Actor-isolated driver for a single embedded Tor instance.

[`TorSession`](/documentation/Tor/TorSession)

Minimal lifecycle interface for driving (or mocking) an embedded Tor
instance.

[`TorConfiguration`](/documentation/Tor/TorConfiguration)

Value-type configuration passed to [`TorClient`](/documentation/Tor/TorClient) at construction time.

### Control protocol

[Using the Tor Control Protocol](/documentation/Tor/ControlProtocolGuide)

Learn to interact with an embedded Tor instance via [`TorControlClient`](/documentation/Tor/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.

[`TorControlClient`](/documentation/Tor/TorControlClient)

`Sendable` high-level client for Tor’s control protocol
(control-spec.txt).

[`ControlSocket`](/documentation/Tor/ControlSocket)

Cross-platform, `Sendable` line-oriented wrapper around a Tor control
socket file descriptor.

[`ControlReply`](/documentation/Tor/ControlReply)

A fully-parsed Tor control-protocol reply, ready for business logic.

[`ControlProtocolParser`](/documentation/Tor/ControlProtocolParser)

Namespace enum holding all stateless control-protocol parsing routines.

### Onion services

[`OnionService`](/documentation/Tor/OnionService)

A successfully-created onion service, as returned by `ADD_ONION`.

[`OnionKeySpec`](/documentation/Tor/OnionKeySpec)

Key-generation policy for an onion service (`ADD_ONION` first argument).

[`OnionPortMapping`](/documentation/Tor/OnionPortMapping)

A single virtual-port → target mapping advertised by an onion service.

[`OnionPortTarget`](/documentation/Tor/OnionPortTarget)

Where an onion service should forward inbound connections.

### Events and state

[`TorEvent`](/documentation/Tor/TorEvent)

Lifecycle and protocol events surfaced by [`TorClient`](/documentation/Tor/TorClient) and
[`TorSession`](/documentation/Tor/TorSession).

[`TorState`](/documentation/Tor/TorState)

Six-case lifecycle enum describing an embedded Tor instance.

[`TorLogLevel`](/documentation/Tor/TorLogLevel)

Tor’s five log-severity levels, surfaced as a typed, ordered enum.

[`TorControlEvent`](/documentation/Tor/TorControlEvent)

Raw-protocol subscription keywords accepted by `SETEVENTS`.

[`TorControlEventMessage`](/documentation/Tor/TorControlEventMessage)

A parsed 650-status async reply from the Tor control protocol.

[`BootstrapStatus`](/documentation/Tor/BootstrapStatus)

Parsed `BOOTSTRAP` status line per control-spec.txt §4.1.11.

### Values

[`HostPort`](/documentation/Tor/HostPort)

Immutable `host` + `port` pair representing a TCP network endpoint.

[`PortPolicy`](/documentation/Tor/PortPolicy)

Three-way policy describing how Tor should bind a configurable port.

[`AddOnionResponse`](/documentation/Tor/AddOnionResponse)

Decoded fields of an `ADD_ONION` success reply
(control-spec.txt §3.27).

### Errors

[`TorError`](/documentation/Tor/TorError)

Canonical error surface for every swift-tor failure mode.

### Apple-only

[`makeURLSession(ephemeral:)`](/documentation/Tor/TorClient/makeURLSession(ephemeral:))

Return a ready-to-use `URLSession` that routes every request
through this Tor instance’s SOCKS5 proxy.