Debugging an Apple TV

An Apple TV is the hardest of the three platforms to debug, for reasons that have nothing to do with Chute: tvOS has no browser, no share sheet, no file browser, no way to install a certificate from the device, and a remote control instead of a keyboard. Chute tvOS answers each of those by moving the interface somewhere else — a browser on your phone or Mac, a QR code, a Dashboard window.

So the shape of this guide is different from the other two: almost everything happens off the television.

1. Get a configuration onto the TV

Editing a configuration with a remote control is not something anyone should do twice, so write it elsewhere and send it over. On the Apple TV, Add Configuration From… offers three routes:

• Upload File Via Wi-Fi or Chute iOS — the TV opens a local HTTP listener and shows a URL and a QR code. Open the URL in any browser and upload the file, or scan the code with Chute iOS. The chute://tv URL scheme opens the same import view in the phone app directly.
• Download From URL — the TV fetches the configuration itself. The least typing of the three, if the file is somewhere it can reach.
• Blank Configuration — an empty one to edit on the device.

For the upload route, the TV and the other device must be on the same Wi-Fi, and the listener only lives while that screen is open — leaving it or locking the device cancels the transfer.

2. Turn on the two listeners you will actually use

Neither is on by default, and the Apple TV is useless to debug without at least one of them. Both are free — the licence on this platform covers the local proxy server rows and the traffic recorder, not these.

HTTP API + Web UI — the Web Console, which is where bodies, HAR exports and diagnostics live:

[General]
external-http-controller = 0.0.0.0:9090
external-http-secret = your-own-token
external-http-ui = true

Bind it to 0.0.0.0, not 127.0.0.1: a loopback console cannot be opened from another device, and there is no browser on the TV to open it locally. A non-loopback bind requires an explicit external-http-secret, or the controller refuses to start.

External Controller Access — the binary channel Chute Dashboard speaks. In the configuration editor open External Controller:

1. External Controller Access on.
2. A Port (6171 is the default here) and a Password of your own; it cannot be empty.
3. Allow Access From Wi-Fi on. On an Apple TV this is not optional the way it is on a phone — there is no cable path to fall back on, so with it off nothing outside the TV can connect.

You should see, on the Control Panel: HTTP API Port and Web UI showing On, and External Access Port showing your port. Missing means the tunnel is running an older copy of the configuration — restart it.

3. Open the console from another device

The Control Panel has a Web UI Address row under the Web UI switch. Select it:

• If the listener is reachable from other devices, the TV shows a QR code. Scan it with a phone on the same network, or type the address into any browser. The sign-in token travels inside the code rather than being displayed, so nobody has to read 32 hex characters off a television.
• If the controller is bound to loopback, the TV shows an explanation instead of a code — see step 2.

From there the console is the same on every platform: Connections with per-request inspection and bodies, Rules with the list of rewrites that have fired, Diagnostics with the ping / DNS / egress / URL-test probes, and Logs.

4. Connect Chute Dashboard

On a Mac, open Chute Dashboard and use the Remote section: Host is the Apple TV's address — the Control Panel shows it under LOCAL IP — with the port and password from step 2. The USB section is for iPhones; an Apple TV is reached over the network.

Everything Dashboard does for a phone it does here — the Active and Recent lists, the DNS and UDP views, the MitM tool panels, HAR and curl exports on a right-click.

5. Decrypting HTTPS

Two things are different on this platform, and both surprise people.

The CA cannot be installed from the app. tvOS has no Safari and no profile installer, so the certificate has to arrive the way tvOS accepts certificates at all: MDM, or Apple Configurator. The app says as much where the hostname list is edited. Generate or import the CA in the configuration as usual, export it, and deliver it to the device by one of those two routes.

There is no MitM switch on the Control Panel. iOS and macOS both have one; tvOS does not. Decryption is turned on by one of:

• the configuration — enable = true in [MITM], which is the durable answer;
• the console, or Chute Dashboard's toolbar switch;
• PUT /api/features/mitm with {"enabled": true}.

The last three act on the running kernel only and are forgotten at the next restart. The hostname list is read from the configuration, and can be edited live from either the console or Dashboard.

[MITM]
enable = true
hostname = api.example.com, *.example.net

6. Recording, and getting the result off the device

Dump Data on the Control Panel is the traffic recorder — the replica setting — and is one of the two licensed switches on tvOS. Without it, connections still appear with their rule, policy and timings; the payloads are simply absent.

Then comes the part that is unique to this platform: the Apple TV has nowhere to put a file. There is no share sheet and no Files app, so every export goes out over HTTP:

• HAR — the console's Connections page, Export HAR. The download lands on the machine running the browser.
• Runtime diagnostic bundle — the console's Diagnostics page, Download diagnostic bundle.
• Offline diagnostic bundle — Settings → Offline Diagnostic Bundle, when the tunnel is not running. The TV builds the archive and shows a QR code; the link works only while that screen is open.

7. What the TV itself can still tell you

Some questions do not need another device at all. Under Settings → DIAGNOSIS:

• Sessions — the run's connections. Selecting one opens a detail panel with BASIC (date, state, close reason, duration), POLICY (the matched rule and the policy it chose), NODES (local, server, remote, host), TRAFFIC, TIMING (proxy ready, DNS resolve, rule, remote ready, total active) and the rewrites that fired. No request or response bodies — those need the console or Dashboard.
• Sessions → the log screen — with a severity filter above it (All / Notify+ / Warning+ / Fatal), so a remote control is enough to narrow a run down to its warnings.
• Network Diagnosis, Proxy Diagnosis, Route Table — reachability, listeners and routing as the device sees them.

The Control Panel also carries Purge DNS Cache, which is the fastest way to retest a [Host] mapping without restarting the tunnel.