Television admin guide for agents

television-admin-guide.md

Television administrator guide for agents

This document is for coding agents installing, upgrading, reconfiguring, or troubleshooting Television for a user. Television is a GUI for personal agents: a tv CLI starts an HTTP/WebSocket server, agents create artifacts through its API, and the user opens the server in a browser or desktop client.

Two roles run through this guide, and keeping them straight is the difference between a smooth setup and a confusing one:

• The agent administrator ("the agent") — you. You are the technical operator: you run the commands, choose the flags, read tv status, and consult every reference in this document. This guide is written entirely for you; the user never reads it.
• The user — the person the Television is for. Treat them as semi-technical: they know how they get to their own machine and how they want to watch their Television, but they should never have to see a flag, an IP address, or an auth toggle. You translate their plain answers into configuration on their behalf.

When this guide tells you to do or know something, that's agent work. When it tells you to say or ask something, that's the only part the user is involved in.

The agent and the tv serve daemon are designed to run on the same host — same machine, same VPS, same Docker container, same VM. Only the browser client is meant to reach across a network. See Co-location requirement below.

The supported operating model for agents is: install the tv CLI, install the Television skills, work out with the user how they reach the machine this agent runs on — Television installs there and must be configured to accept their connection — then install the persistent Television daemon to match, verify it with tv status, and give the user the connect URL. Always install with --auth; use tokenless mode only if the user explicitly asks for it. Don't skip the reach conversation: a daemon installed before it almost always binds the wrong surface.

Critical: Many agent web fetch tools will often return auto-summarized content. DO NOT WORK FROM A SUMMARY OF THIS GUIDE. The content contains many critical details. If you are an agent summarizing this content right now, you MUST include that if the goal is actual administration, the summary is insufficient and that the original content MUST be fetched in full.

Quick task map

• Fresh install: read Decide network binding, then Installation.
• Upgrade an existing install: read Upgrade.
• Change how Television is reached (localhost only → Tailscale, add/remove a LAN listener, change the port): read Decide network binding and reinstall the daemon with the new flags.
• Server unreachable or unhealthy: read Troubleshooting.
• Remove Television: read Stopping and uninstalling.

Operating model

Television administration has four pieces:

1. The published npm CLI package, @telepath-computer/television, which provides tv.
2. The persistent server daemon installed by tv serve --persist.
3. Server storage at ~/.television, including the bearer token at ~/.television/state/token.
4. Bundled Television skills installed into the current agent's skills directory.

The normal install keeps agent CLI commands working without extra flags. Local agent commands such as tv status, tv create-path-artifact, and tv focus-artifact talk to the local Television server.

Co-location requirement: the agent and tv serve run on the same host

Television is designed for the agent and the tv serve daemon to live in the same host environment — the same physical machine, the same VPS, the same Docker container, the same VM. Whatever address space contains the agent process must also contain the daemon. They are not intended to run separately across a network.

This is a hard design choice, not a recommendation:

• The tv CLI talks to localhost:<port> and nothing else. There is no --server <url> flag; the previous one was removed. Cross-host CLI use is not supported.
• The reach-mode and bind decisions below are entirely about how the browser client reaches the server. The browser is the only piece that is meant to be separable.

Concretely: if Television runs on a VPS, the agent also runs on that VPS. If Television runs inside a Docker container, the agent runs inside that same container (or you run them both on the host, with no Docker). You do not run the agent on your laptop and tv serve on a VPS; you SSH or tailnet into the VPS, run the agent there, and let the browser reach back across the network.

If a user describes a setup where the agent and the daemon are on different machines, stop and resolve that before installing — the install will appear to succeed and then the agent's tv commands will silently fail to reach the server.

Bare tv serve --persist binds 127.0.0.1 and runs tokenless for compatibility, which is why the standard install command is tv serve --persist --auth so the server requires the bearer token even on loopback. Keep the default port (32848) unless the user has an unavoidable conflict; both the daemon and the tv CLI resolve the port independently, and changing it durably requires exporting TELEVISION_PORT from the user's shell init so every future agent session picks the same value (see the port question in Decide network binding). To expose additional IPv4 listeners, pass repeated or comma-separated --listen <ipv4> values and include --auth.

Television is intended to be used over local loopback or a private network such as Tailscale. Treat the bearer token like a password. The agent does not know, and cannot infer from the host alone, how the user wants the server reached — that is an interview decision; see Decide network binding.

Decide network binding

Television installs on the machine where the user's primary personal agent runs — the machine this agent is on. That isn't a decision to make. The one thing to work out is how the user reaches that machine from wherever they physically sit, because that is exactly how they will reach Television. You arrive at that through a short conversation, then translate it into --listen flags yourself — the user never sees a flag.

Two rules, no exceptions:

1. Never install before the conversation. Do not run tv serve --persist until you have worked out, with the user, how they reach this host. A silent install binds the wrong surface and only looks like success.
2. Never interrogate with jargon. Do not put a menu of reach modes or IP literals to the user, and do not discuss auth unless the user raises it. They chose an agent precisely so they would not have to learn any of this.

Everything below the conversation is agent reference — the server's rules and the answer-to-flag mapping, written for you and you alone. Consult it while talking; never read it, its flags, or its IP addresses back to the user. The instructions you actually act on are in The conversation.

The server's flag rules (agent reference):

• Localhost (127.0.0.1) is always bound; you cannot turn it off.
• Seatbelt principle: auth is always on for agent installs. Omit --auth only when the user explicitly asks to run tokenless for an unusual reason.
• Bare tv serve (no --listen) is localhost-only and tokenless by default for compatibility. That back-compat default is why agents pass --auth explicitly; --auth requires the token on every request, including loopback.
• Any --listen <ipv4> requires an explicit --auth or --no-auth. Agents supply --auth unless the user explicitly requested tokenless mode.
• --listen accepts repeatable flags or a comma-separated list and validates each IPv4 literally. The IP must already be assigned to the host at install time (and at every daemon restart) or that listener will fail to bind.
• The auth posture is global. There is no per-listener auth — --auth enforces the bearer token on every listener including localhost, and --no-auth disables it on every listener.

The conversation

Work through four beats, in plain language, one thing at a time:

1. Explain the premise — don't just jump to a question. In a sentence or two, tell the user why you're asking: Television runs right here on the machine their agent runs on (it is not a service hosted somewhere else), so the one thing to set up is making it reachable from wherever they actually do their computing. Give them that picture before you ask anything; a bare "how do you reach this machine?" with no framing leaves a semi-technical user guessing at what you mean. See Co-location requirement.
2. Work out how they reach this machine. This is the heart of the interview. Ask how they get to this machine today and let the answer set the binding: sitting right at it → localhost, expose nothing; they SSH in → an SSH tunnel over the connection they already use; they use Tailscale → bind the tailnet address; it is a machine on their own network → a LAN bind. Ask, listen, and follow up only as needed. If the agent runs inside a container the mechanics differ — see Docker.
3. Confirm where the skills will be installed. Television ships skills that must land in this agent's skills directory, and there is no single standard location — it varies by agent framework and by how the user set things up. Do not silently guess. Work out the most likely directory for this agent (see Install Television skills for the common locations), propose it in one plain sentence, and get a yes before installing. Example: "I'll put the Television skills in ~/.openclaw/workspace/skills — that's where this agent loads them from. Sound right?"
4. Confirm the plan, then install. Say back in one plain sentence what you're about to do — how they'll reach it and where the skills go — then proceed to Install the daemon. No further questions are needed once they've confirmed.

A good opening explains before it asks: "Television runs right here on the same machine I'm on — it's not hosted anywhere else — so the main thing to sort out is how you'll get to it from wherever you actually work. When you want to look at it, are you sitting at this machine, or reaching it from another device — say over SSH, Tailscale, or your home network?" That framing gives a semi-technical user the picture first; from their answer you can usually settle the rest with one short follow-up.

Never repeat either failure: silently running the install (then reporting a healthy tv status the user cannot actually reach), or handing the user the reach options as a checklist to fill in. Both leave a daemon running and both are wrong.

Port (agent reference)

Strongly prefer the default 32848. Do not change the port unless you have a durable way to make both the daemon and every future tv CLI invocation agree on the new value, and the user has a real reason (e.g., an unavoidable port conflict) to deviate.

The problem with --port: the daemon and the tv CLI resolve the port independently as flag → TELEVISION_PORT env → 32848. If you install the daemon with --port 40000 but TELEVISION_PORT is not exported globally, every later tv command this session — or any future agent session — defaults back to 32848 and quietly fails to reach the server. Agents will not remember to pass --port on every future CLI call, and a fresh agent context will not know that this user's Television runs on a non-default port.

If the user must change the port, the only safe path is:

1. Set TELEVISION_PORT=<n> in the user's shell init (~/.bashrc, ~/.zshrc, ~/.profile, fish equivalents, or whatever the user actually uses) so it is exported in every future shell, including future agent shells. Verify with env | grep TELEVISION_PORT in a freshly opened terminal.
2. Then install the daemon from a shell that has TELEVISION_PORT set. The daemon captures TELEVISION_PORT into its persisted environment at install time.
3. Skip the --port flag entirely if TELEVISION_PORT is set; the env var is enough.

If the user does not want to edit their shell init, keep the default port and resolve the conflict at the other end (move or stop the conflicting service). A future agent has no realistic way to discover a per-install port override.

For SSH tunnels, the -L forward should target the same port on both ends to keep the URL http://localhost:32848 on the user's laptop. For Docker, the docker run -p <host>:<container> mapping should use the same port on both sides for the same reason.

Translate the answers into flags (agent reference)

Reach mode	--listen	Auth flag
Localhost only	omit	--auth
SSH tunnel (VPS or any remote host)	omit — daemon is localhost-only; user runs ssh -L 32848:localhost:32848 user@host	--auth
Tailscale only	--listen $(tailscale ip -4)	--auth
Localhost + Tailscale	--listen $(tailscale ip -4) (localhost is always added)	--auth
LAN (single interface)	--listen <lan-ipv4>	--auth
LAN (every interface)	--listen 0.0.0.0	--auth
Docker, host loopback only	inside container: --listen 0.0.0.0; host publish: docker run -p 127.0.0.1:32848:32848 ...	--auth
Docker, host LAN	inside container: --listen 0.0.0.0; host publish: docker run -p 32848:32848 ... (or 0.0.0.0:32848:32848)	--auth
Mix of the above	comma-separated or repeated --listen	--auth

Every agent install uses --auth regardless of reach mode. --no-auth exists only for the rare case where the user explicitly asks to run without a token.

Television is meant to run beside the agent on a host the user already reaches privately — local, SSH, Tailscale, or their own LAN. It is not designed to be exposed directly to the public internet, which is why there is no public-reach row above. If a user insists on that anyway, treat it as an explicit, separately-confirmed exception, always paired with --auth.

Any server started without auth prints a stderr warning that the tokenless server is open to browser pages the operator opens, and writes the choice to <storagePath>/logs/tv.log. When non-loopback listeners are present, the warning names them. That warning is not an error — it is the operator's audit trail for the rare explicit user request to run unauthenticated.

Literal IP capture caveat (agent reference)

--listen values are captured literally into the launchd plist or systemd unit at install time. They are not re-resolved at daemon restart.

• --listen $(tailscale ip -4) evaluates in the installing shell. The actual numeric IP is what lands in the unit file. If the tailnet IP later changes (rare but possible: account changes, re-registration, multi-account devices), the daemon will fail to bind that address on the next restart. Recovery is tv serve --persist-uninstall followed by a fresh tv serve --persist --listen $(tailscale ip -4) --auth.
• Same caveat for DHCP-assigned LAN addresses. If the user's host gets a new LAN IP, the persisted listener stops working until the daemon is reinstalled.
• --listen 0.0.0.0 sidesteps this because the wildcard binds whatever interfaces exist at startup. The trade-off is that future interfaces are also exposed.

Tell the user the recovery command in advance — "if your Tailscale or LAN IP ever changes, re-run tv serve --persist --listen ... --auth" — so they aren't surprised later.

Docker (agent reference)

When Television runs inside a Docker container, the bind decision splits in two: where Television listens inside the container, and how Docker publishes that port on the host.

The co-location requirement still applies: the agent runs inside the same container as tv serve. The docker run -p mapping is purely for the browser to reach the server. Do not run the agent on the host and the daemon in a container (or vice versa) — the tv CLI talks only to its own loopback and will not cross the container boundary.

Key facts:

• The container has its own network namespace. 127.0.0.1 inside the container is not the host's 127.0.0.1 — it is only reachable from inside the same container. A localhost-only tv serve inside a container cannot be reached from the host, from other containers, or from the network.
• For Television to be reachable from outside the container, the daemon must bind to 0.0.0.0 inside the container. Use --listen 0.0.0.0 --auth.
• Where the port is exposed on the host is controlled by docker run -p <host>:<container>. That host-side bind, not the in-container bind, is what determines the actual trust boundary.

Pattern recommendations:

• Browser on the same host as Docker. Publish to host loopback only:

  docker run -p 127.0.0.1:32848:32848 ...

  Inside the container, run tv serve --persist --listen 0.0.0.0 --auth. User opens http://localhost:32848 on the host.

• Browser on another device on the LAN. Publish to all host interfaces (Docker's -p 32848:32848 default) and run the daemon with auth:

  docker run -p 32848:32848 ...

  Inside the container, tv serve --persist --listen 0.0.0.0 --auth. The host's firewall must allow inbound 32848.

• Browser on another machine via Tailscale. Two options:

  1. Run Tailscale on the host and publish to the host's tailnet IP: docker run -p $(tailscale ip -4):32848:32848 ... plus --listen 0.0.0.0 --auth inside.
  2. Run Tailscale inside the container (e.g., the tailscale/tailscale sidecar). The container then has its own tailnet IP and Television can be reached on http://<container-tailscale-ipv4>:32848. Use --listen 0.0.0.0 --auth inside the container; no docker run -p is needed in this case.

• VPS running Docker. Same advice as the bare-VPS case: prefer an SSH tunnel. Publish only to host loopback (-p 127.0.0.1:32848:32848) and have the user ssh -L 32848:localhost:32848 user@vps-host. Public publishing on a VPS (-p 0.0.0.0:32848:32848) is the same risk surface as a bare --listen 0.0.0.0 on a VPS and requires --auth.

User-side checklist when Television runs in Docker:

• The published host port matches what the user is trying to open in the browser.
• The host's firewall allows that port (for LAN or public publishing).
• The tv CLI on the host cannot talk to a Docker-only Television unless the port is published to host loopback or the user runs tv inside the container — the tv client speaks localhost:<port> only and does not cross the host/container boundary.

Installation

Install the CLI

Install the published npm package so the tv binary is available:

npm install -g @telepath-computer/television

Verify:

tv --help
tv --version

If global npm installs are not appropriate on the host, use the user's preferred Node package setup. Ensure the tv command you run is the intended installed CLI before creating the daemon.

Install Television skills for the agent

Identify the current agent's skills directory, then propose it to the user and get a yes before installing (this is a beat in the conversation) — locations vary widely and a silent guess often lands the skills where the agent can't load them. Common locations:

• Shared agent setups often use ~/.agents/skills.
• OpenCLAW often uses ~/.openclaw/workspace/skills for an agent's skills directory, but also supports ~/.agents/skills.
• Hermes often uses ~/.hermes/skills.
• Claude Code, Codex, and other sidecar agents may have their own skills/instructions location; use the user's preferred location when known.

If the user has given you specific instructions on where they prefer their skills to live, respect those. Install the bundled Television skills into the appropriate directory:

tv skills install <skills-directory>

For example, for a default OpenCLAW setup:

tv skills install ~/.openclaw/workspace/skills

Confirm that the installed skills are now available to you after installing them, including any refreshing as needed. Missing skills produces a frustrating user experience.

Pre-load the main television skill

If the user is installing TV for the first time, assume the user will want to explore the Television experience right away. Have the skill loaded already so you can make sense of any initial fast-follow requests to add content to the TV.

Install the daemon

Stop. Do not run this until you have had the conversation about how the user reaches this host. Installing first — before you know how they connect — is the single most common way this goes wrong; a healthy tv status on the wrong binding is not success.

Compose the install command from two pieces:

1. tv serve --persist.
2. The --listen, --auth, and --port flags from Decide network binding.

Examples by reach mode:

# Localhost only, standard token-protected install — also works for SSH-tunnel access
tv serve --persist --auth

# Tailscale + localhost, token required
TAILSCALE_IP="$(tailscale ip -4)"
tv serve --persist --listen "$TAILSCALE_IP" --auth

# LAN on a specific interface, token required
tv serve --persist --listen 192.168.1.42 --auth

# Wildcard (all interfaces), token required
tv serve --persist --listen 0.0.0.0 --auth

# Multiple listeners, one global auth posture
tv serve --persist --listen "$TAILSCALE_IP" --listen 192.168.1.42 --auth

Reminders the install must respect:

• Any --listen requires exactly one of --auth or --no-auth. Agents use --auth; the CLI rejects non-loopback installs without an explicit auth flag.
• --no-auth is legal but the server will print a stderr warning at startup and log the choice. Use this only when the user explicitly asks to run without a token; a tokenless server accepts API control from browser pages the operator opens.
• tv serve --persist re-runs uninstall + install. To change flags, run tv serve --persist again with the new flags.

Do not run plain tv serve (without --persist) as a smoke test unless you intentionally manage it as a long-running foreground server process. Plain tv serve starts the server in the foreground and does not exit on success, so it will hang an automated agent session. Install the daemon, then check it from a separate command.

Check health

Verify the server and daemon:

tv status

The result should report healthy: true and a daemon status with installed: true and running: true on supported platforms.

You can also verify the local health endpoint directly:

curl -fsS http://localhost:32848/health

For an API check, call a real API route. Standard installs use auth, so include the token:

TOKEN="$(cat ~/.television/state/token)"
curl -fsS -H "Authorization: Bearer $TOKEN" http://localhost:32848/screens

User connection URL

After installation, tell the user how to open Television. Use the listener that matches how they will actually reach it:

# Same machine
http://localhost:32848

# SSH tunnel: user runs `ssh -L 32848:localhost:32848 user@host`, then opens
http://localhost:32848

# Tailscale (from another tailnet device)
http://<tailscale-ipv4>:32848

# LAN (from another device on the same network)
http://<lan-ipv4>:32848

For SSH tunnels, give the user the full ssh command, not just the URL. They will need to run it (and keep that terminal open) before the URL works.

tv status prints every bound URL the daemon is currently serving — read that and quote the appropriate one back to the user rather than guessing. If the daemon partially failed to bind (e.g., the Tailscale IP changed since install), tv status and tail ~/.television/logs/tv.log will show which addresses actually came up.

Give the user the URL. When the daemon was installed with --auth, read ~/.television/state/token and give the user a complete authenticated browser URL (<server-url>/?token=<token>) as the primary click target. Also print the complete, untruncated token by itself — the whole string, not a prefix or summary — plus the file path (~/.television/state/token) as a fallback for manual entry, the desktop client's token field, and password-manager storage. For a tokenless daemon, give the bare URL, tell them no token is required, and mention that the server is open to local processes and browser pages they open. Tailscale remains the preferred remote-access path; a LAN bind is supported but puts more of the trust on the user's network and on the bearer token.

Also decide whether to offer the desktop client: it uses the same server URL and is the only client that renders URL artifacts as full external web page content rather than a placeholder.

Desktop client (recommended for URL artifacts)

Television has an Electron desktop client. The principal reason to install it is full support for URL artifacts. Browser clients show a placeholder for URL artifacts; the Electron client renders external web pages and local web apps inside the artifact card via webview. If the user wants to display external web pages on a TV screen, the desktop client is the only real option.

The desktop client also provides a native app experience — a real window, Dock icon, and OS integration — which some users prefer over a browser tab. That's a secondary benefit; URL artifact support is the main one.

Install:

npm install -g @telepath-computer/television-desktop

Launch:

tv-desktop

The desktop client opens a connect window; point it at the server URL above. Enter the token. Tokenless servers leave the token field blank only when the user explicitly asked to run without a token.

On macOS, the first launch renames the bundled app to "Television" in the Dock and menu bar. First launch is slightly slower; subsequent launches are fast.

When walking the user through install, ask whether they intend to use URL artifacts (external web pages or web apps on their TV). If yes, install the desktop client now. If they're unsure or only want path artifacts, mention that the desktop client can be installed anytime later.

Upgrade

1. Identify the current CLI and version:

   which tv
   tv --version
   npm list -g @telepath-computer/television --depth=0

2. Upgrade the CLI package:

   npm install -g @telepath-computer/television@latest

3. Reinstall bundled skills. Skill content is expected to change across releases, so update the skills whenever you update the CLI:

   tv skills install <skills-directory>

4. Reinstall the daemon using the same listen/auth/port/storage settings the user needs. Before running anything, check the current daemon's flag set so you can preserve it:

   tv status                                            # bound URLs and resolved settings
   # macOS:
   cat ~/Library/LaunchAgents/com.television.server.plist | grep -A1 -E 'listen|auth|port'
   # Linux:
   cat ~/.config/systemd/user/com.television.server.service | grep ExecStart

   Then reinstall, repeating the same --listen / --auth / --port the existing daemon used (or take the user back through the interview if they want to change how they reach it). Preserve --no-auth only when the user explicitly asked to run without a token:

   # Tailscale + auth preserved
   TAILSCALE_IP="$(tailscale ip -4)"
   tv serve --persist --listen "$TAILSCALE_IP" --auth
   
   # Localhost only + auth
   tv serve --persist --auth
   
   # LAN + auth
   tv serve --persist --listen 192.168.1.42 --auth

   An upgrade that drops --listen or --auth silently downgrades the surface (e.g., a Tailscale-reachable daemon becomes localhost-only again). Preserve the flags or tell the user the surface is changing.

5. Verify health:

   tv status

An npm package upgrade does not require deleting ~/.television; keeping storage in place preserves screens, artifacts, and the existing token. Delete storage only when the user explicitly wants a permanent reset.

Stopping and uninstalling

Stop and remove the persistent daemon:

tv stop

tv stop uninstalls the persisted launchd/systemd service and stops the Television server process managed by that service. It is not just a temporary pause command; after tv stop, Television will not start again on login/boot until tv serve --persist is run again. It does not remove the npm package, skills, or ~/.television storage.

To remove the npm package:

npm uninstall -g @telepath-computer/television

To remove installed skills, delete the television skill and any tv-* skills from the agent's skills folder(s). Due to a diversity of skill folder locations for most agents, be thorough in searching them out.

To permanently remove server data, delete the storage directory, usually ~/.television. Deleting storage is non-recoverable unless the user has backups; it removes screens, artifacts, and the token. Always ask for confirmation before deleting the user's television storage directory.

Troubleshooting

Start with the built-in status check:

tv status

Then check the local HTTP endpoint and durable log:

curl -fsS http://localhost:32848/health
TOKEN="$(cat ~/.television/state/token)"
curl -fsS -H "Authorization: Bearer $TOKEN" http://localhost:32848/screens
# for deliberate tokenless installs only:
curl -fsS http://localhost:32848/screens
tail -n 200 ~/.television/logs/tv.log

Common issues:

• Daemon is not installed or not running. Reinstall: tv serve --persist --auth (add --listen flags as needed for the user's reach mode; use --no-auth only if the user explicitly asks to run without a token).

• Port already in use. Stop the conflicting service or stop/reinstall Television after the conflict is resolved. Prefer resolving the conflict on the other side rather than moving Television off 32848; see the port discussion in Decide network binding for why a non-default port is hard to keep working long-term.

• tv CLI cannot reach a server installed on a non-default port. Almost always because TELEVISION_PORT is not exported in the shell where tv is being run. Check env | grep TELEVISION_PORT. If the daemon was installed with --port <n> but TELEVISION_PORT is not set globally in shell init, fix it by adding export TELEVISION_PORT=<n> to the user's ~/.bashrc / ~/.zshrc / equivalent and reinstalling the daemon from a shell that has the variable set. If the user does not want to edit shell init, reinstall the daemon on the default port 32848.

• Token mismatch. Read the current token from ~/.television/state/token, make sure the user has copied it exactly, and test it against the local server:

  TOKEN="$(cat ~/.television/state/token)"
  curl -fsS -H "Authorization: Bearer $TOKEN" http://localhost:32848/screens

  If the curl command succeeds, the token is valid and the user's browser/client likely has a copied, stale, or malformed token. Give the user the current token again.

• Skills installed to the wrong directory. Reinstall skills into the agent framework's active skills directory.

• User cannot open the GUI remotely. Establish how they are reaching the host. For an SSH tunnel, confirm the ssh -L <port>:localhost:<port> user@host command is running and the user is opening http://localhost:<port> on the laptop side; the daemon side should be a normal localhost-only install (tv serve --persist --auth with no --listen). For Tailscale, confirm tailscale ip -4 returns an address and that the daemon was installed with --listen <tailscale-ip> --auth; give the user http://<tailscale-ip>:32848 and the token. For a LAN bind, confirm the matching --listen actually came up in tv status and that the user's firewall lets the port through.

Platform locations and commands:

• macOS plist: ~/Library/LaunchAgents/com.television.server.plist
• macOS daemon status: launchctl list com.television.server
• Linux user unit: ~/.config/systemd/user/com.television.server.service
• Linux daemon status: systemctl --user status com.television.server.service

What to tell the user

Give the user:

1. The URL to open in their browser.
2. Whether a token is required.
   • If --auth is enabled: read the token with cat ~/.television/state/token, append it to the chosen browser URL as ?token=<token>, and give that complete authenticated URL as the primary link to click. Also print the complete, untruncated token by itself and name the file path in case they need manual entry, the desktop client's token field, password-manager storage, or retrieval later.
   • If tokenless: give the bare URL, tell the user no token is required, token fields stay blank, and the server is open to local processes and browser pages they open.
3. The desktop client situation. URL artifacts (external web pages and web apps on a TV screen) only render in the Electron desktop client; browser clients show a placeholder.
   • If the desktop client was already installed during setup: tell the user they can launch it with tv-desktop, and they should use it when they want to display external web pages.
   • If it was not installed: explain that the browser URL still works for file-backed artifacts, but URL artifacts won't render fully there. Offer to install the desktop client (npm install -g @telepath-computer/television-desktop; launch with tv-desktop) if they want external-web-page support, or note that they can install it later anytime.
4. What changed: installed, upgraded, reconfigured, or troubleshot.
5. How to stop or reinstall the daemon if needed.

Examples:

Tailscale install:

Television is installed and running.
Open it — this link has your token built in, just click:
  http://100.x.y.z:32848/?token=k7m2-9xPq4nV8R3jL1cBwA6sYfHzD0eUtG5oI-token-example-untruncated-string
Your token (only if you enter it by hand — e.g. the desktop client's token field — or to save it; file: ~/.television/state/token):
  k7m2-9xPq4nV8R3jL1cBwA6sYfHzD0eUtG5oI-token-example-untruncated-string

Desktop client (recommended if you want external web pages on your TV):
  Not yet installed. To install:
    npm install -g @telepath-computer/television-desktop
  Then launch: tv-desktop

I installed the persistent Television daemon and updated the Television skills.
If the machine's Tailscale IP changes, run `tailscale ip -4` and reinstall:
  tv serve --persist --listen "$(tailscale ip -4)" --auth

SSH-tunnel install (VPS):

Television is installed and running on the VPS, localhost-only.
To open it, run on your laptop:
  ssh -L 32848:localhost:32848 user@vps-host
Then open it — this link has your token built in, just click after the SSH tunnel is up:
  http://localhost:32848/?token=k7m2-9xPq4nV8R3jL1cBwA6sYfHzD0eUtG5oI-token-example-untruncated-string
Your token (only if you enter it by hand — e.g. the desktop client's token field — or to save it; file: ~/.television/state/token):
  k7m2-9xPq4nV8R3jL1cBwA6sYfHzD0eUtG5oI-token-example-untruncated-string

Desktop client: optional. If you want URL artifacts (external web pages on your TV), install the desktop client locally on your laptop:
  npm install -g @telepath-computer/television-desktop
The desktop client connects to the same URL (http://localhost:32848 via the SSH tunnel) and uses the same token.

I installed the persistent Television daemon and updated the Television skills.
Keep the ssh -L session open while you use the GUI.

Agent checklist

1. Determine the task: install, upgrade, troubleshoot, or uninstall.
2. Have the conversation about how the user reaches this host (sitting at it / SSH / Tailscale / their own LAN) — in plain language, before installing anything, never a jargon checklist. Translate the answer into --listen yourself and include --auth. See Decide network binding.
3. Install or upgrade @telepath-computer/television if needed.
4. Install bundled Television skills into the directory you proposed and the user confirmed during the conversation — don't silently guess the location.
5. Install/reinstall with tv serve --persist --auth plus any needed --listen flags. An SSH-tunnel setup is still a localhost-only install on the server side. Use tokenless mode only if the user explicitly asks to run without a token.
6. Verify tv status.
7. Give the user the full authenticated browser URL (and, for SSH tunnels, the ssh -L command) and any relevant operational notes. For --auth installs, also print the complete, untruncated token and token file path as the manual-entry fallback. For tokenless installs, give the bare URL, say no token is required, and say the server is deliberately open on that host.
8. Cover the desktop client in the final response. URL artifacts only render fully in the Electron desktop client; browsers show a placeholder.
   • If the user wants URL artifact support and you have not installed the desktop client yet, offer to install it now (npm install -g @telepath-computer/television-desktop; launch with tv-desktop).
   • If you installed it earlier in this flow, remind the user how to launch it (tv-desktop) and that it's the right client for URL artifacts.
   • If the user has no URL artifact intent and declined, note that they can install it later anytime.