---
title: "Task Recipes"
description: "Share a report, preview a local web app, connect an agent, and access raw TCP over a tailnet"
url: "https://tslink.md/docs/use-cases"
locale: "en"
product_version: "0.1.1"
source: "https://github.com/anydoor7/tslink/blob/v0.1.1/docs/sharing.md"
---

> Documentation index: https://tslink.md/llms.txt · Installed binary is authoritative: `tslink manifest`.

Scenario guides: [Use your coding agent's web UI from your phone](https://tslink.md/docs/agent-ui-phone.md) · [Share one HTML report privately, with an end date](https://tslink.md/docs/private-html-report.md) · [Share an app, not your whole machine](https://tslink.md/docs/share-one-app.md).

## Before you start

These are workflows you can try, not adoption claims. [Install TSLink](https://tslink.md/docs/installation.md). Receiving devices need Tailscale and permission under your tailnet policy. First use may return `needs_login`: complete its browser authorization, then use `url --wait`. `share` and `add` ensure the gateway is running by default.

## Share an agent-generated report with your phone

After an agent writes a real HTML report, share only that file:

```bash
tslink share ./report.html --name report --json
tslink url report --wait --json
```

Read `data.status` from the first result. If it is `needs_login`, show `data.auth_url` to the user and wait for authorization before the second command. If ready, use `data.url`. Open the exact returned HTTPS URL on a permitted phone in the tailnet. A file target keeps sibling files out of this share; a directory target shares its browsable contents.

When finished:

```bash
tslink remove report --json
```

Local removal and remote device cleanup are separate results. Ephemeral tailnet-node cleanup does not delete a local registry entry.

## Preview an existing web app on another device

Start your application using its normal development command, then register its listening port:

```bash
tslink add preview --proxy localhost:3000 --allow you@example.com
tslink url preview --wait
```

Replace the example email with the receiving device's real Tailscale login identity. The backend process keeps running independently. Its HTTP proxy receives WhoIs-derived identity headers when available; incoming identity headers are stripped. Tailnet network policy and your application's own authorization still apply.

## Let a local agent manage shares through MCP

Configure your MCP client to launch the installed binary:

```json
{"mcpServers":{"tslink":{"command":"tslink","args":["mcp"]}}}
```

Call `share` with `{"target":"/absolute/path/report.html","name":"report"}`. Treat `needs_login` as a successful human handoff, then call `url` with `{"name":"report","wait":"30s"}`. Use `list` to inspect exact runtime URLs and `unshare` for cleanup. The [MCP reference](https://tslink.md/docs/mcp-server.md) lists all 44 owner tools, with reduced sessions exposing fewer and their complete input fields.

## Reach an existing MCP server from another tailnet machine

If your MCP server already offers HTTP on a local port, register it as an ordinary proxy:

```bash
tslink add mcp-backend --proxy localhost:8080 --allow you@example.com
tslink url mcp-backend --wait
```

Point a tailnet-local MCP client to the returned origin plus the backend's actual MCP path (for example `/mcp`). TSLink forwards HTTP; it does not convert stdio into HTTP or replace MCP/application authorization. See [MCP Server Hosting](https://tslink.md/docs/mcp-hosting.md). To control TSLink itself remotely, use its separate opt-in [remote MCP control plane](https://tslink.md/docs/mcp-server.md#remote-mcp-control-plane).

## Access a database over raw TCP

```bash
tslink add database --tcp localhost:5432
tslink url database --wait
```

Use the exact returned host and port in your database client. TCP forwards bytes and has no HTTP identity headers or TSLink `--allow` check. Protect it with tailnet ACLs/grants and the database's own authentication. Per-service nodes provide network identities, not process or host isolation.

## Diagnose a pending link

```bash
tslink status --json
tslink doctor --json
tslink logs --source err --last 50
```

Read credential storage, node authorization, supervision, and runtime evidence separately. A live process alone does not prove another device can reach the service. Access and application logs go to stderr (`tslink.err.log`). CLI logs are verbatim; the MCP `logs` tool returns a bounded, redacted window, which is not a secret-access boundary for an agent with a shell.

## People, local models and self-hosted apps

[Share an app for seven days](https://tslink.md/docs/people-sharing.md), [connect an existing local model](https://tslink.md/docs/local-ai.md), or [check app health and uploads](https://tslink.md/docs/health-and-alerts.md). Use `tslink apps list` to review the recipe catalog; `tslink apps share jellyfin` previews a route, and `--yes` applies it. Applications remain separately installed and configured.