<!--
{
  "availability" : [

  ],
  "documentType" : "symbol",
  "framework" : "Tor",
  "identifier" : "/documentation/Tor/TorControlClient",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Tor"
    ],
    "preciseIdentifier" : "s:3Tor0A13ControlClientC"
  },
  "title" : "TorControlClient"
}
-->

# TorControlClient

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

```
final class TorControlClient
```

## Overview

Wraps a [`ControlSocket`](/documentation/Tor/ControlSocket) and exposes a typed, `async` method per
control-protocol command family: authentication, `GETINFO`,
`SETCONF`, `SETEVENTS`, `SIGNAL`, `ADD_ONION` / `DEL_ONION`.
Every method sends exactly one command and awaits a single reply
(or an async event stream in the case of [`subscribe(to:)`](/documentation/Tor/TorControlClient/subscribe(to:))),
translating reply codes into [`TorError`](/documentation/Tor/TorError) cases and typed
payloads via [`ControlProtocolParser`](/documentation/Tor/ControlProtocolParser).

Most callers never construct one directly — [`start()`](/documentation/Tor/TorClient/start())
creates a pre-authenticated instance and hands it out via
[`control()`](/documentation/Tor/TorClient/control()). Construct directly when driving a Tor
instance swift-tor did not launch (e.g. connecting to a
systemd-managed `tor` over its `ControlPort`).

### Onion-service lifecycle

[`addOnion(key:ports:detach:)`](/documentation/Tor/TorControlClient/addOnion(key:ports:detach:)) registers an onion service whose
lifetime is determined by the `detach` flag:

- `detach: false` — service is tied to **this** control connection
  and is removed by Tor when the socket closes
  (control-spec.txt §3.27).
- `detach: true` — service survives the control-socket closure and
  only disappears on explicit ``doc://Tor/documentation/Tor/TorControlClient/delOnion(_:)-7ei4o`` or on Tor
  process exit.

> Note: Conformance is `Sendable` (compiler-verified, no
> `@unchecked`). Concurrent calls are safe and serialised at the
> socket layer — commands execute in arrival order.

> Important: ``doc://Tor/documentation/Tor/TorControlClient`` is authenticated at most once per
> instance; subsequent calls to ``doc://Tor/documentation/Tor/TorControlClient/authenticate(password:)`` after
> success are no-ops. For the embedded control socket
> (``doc://Tor/documentation/Tor/TorControlClient/init(fileDescriptor:preAuthenticated:dataDirectory:)`` with
> `preAuthenticated: true`) authentication is skipped entirely.

## Topics

### Creating

[`init(socket:dataDirectory:)`](/documentation/Tor/TorControlClient/init(socket:dataDirectory:))

Wrap an existing [`ControlSocket`](/documentation/Tor/ControlSocket).

[`init(fileDescriptor:preAuthenticated:dataDirectory:)`](/documentation/Tor/TorControlClient/init(fileDescriptor:preAuthenticated:dataDirectory:))

Wrap a raw file descriptor, optionally marking it as
pre-authenticated.

[`init(host:port:dataDirectory:)`](/documentation/Tor/TorControlClient/init(host:port:dataDirectory:))

Open a TCP connection to a listening Tor control port and wrap
it.

### Authentication

[`authenticate(password:)`](/documentation/Tor/TorControlClient/authenticate(password:))

Perform the `AUTHENTICATE` handshake (control-spec.txt §3.5).

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

`true` once any successful `AUTHENTICATE` (or pre-auth
construction) has marked this client ready.

### GETINFO

[`getInfo(_:)`](/documentation/Tor/TorControlClient/getInfo(_:)-6m7om)

Issue a multi-key `GETINFO` command (control-spec.txt §3.9).

[`getInfo(_:)`](/documentation/Tor/TorControlClient/getInfo(_:)-7ru8l)

Convenience: issue `GETINFO` for a single key.

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

Fetch and parse Tor’s current bootstrap status.

### Configuration & events

[`setConf(_:)`](/documentation/Tor/TorControlClient/setConf(_:))

Issue a `SETCONF` command to mutate Tor’s runtime configuration.

[`subscribe(to:)`](/documentation/Tor/TorControlClient/subscribe(to:))

Subscribe to Tor async events and return a stream of decoded
messages.

### Onion services

[`addOnion(key:ports:detach:)`](/documentation/Tor/TorControlClient/addOnion(key:ports:detach:))

Register an ephemeral v3 onion service via `ADD_ONION`
(control-spec.txt §3.27).

[`delOnion(_:)`](/documentation/Tor/TorControlClient/delOnion(_:)-7ei4o)

Remove an ephemeral onion service by its service ID
(`DEL_ONION`, control-spec.txt §3.28).

[`delOnion(_:)`](/documentation/Tor/TorControlClient/delOnion(_:)-xgca)

Convenience overload: delete an onion service by value.

### Signals

[`signal(_:)`](/documentation/Tor/TorControlClient/signal(_:))

Send a `SIGNAL` command to Tor (control-spec.txt §3.7).

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

Ask Tor to rotate circuits (`SIGNAL NEWNYM`).

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

Ask Tor to exit cleanly (`SIGNAL SHUTDOWN`).

### Escape hatch

[`sendRaw(_:)`](/documentation/Tor/TorControlClient/sendRaw(_:))

Escape-hatch: send an arbitrary control command and return the
concatenated reply body.