Task Recipes

Scenario guides: Use your coding agent's web UI from your phone · Share one HTML report privately, with an end date · Share an app, not your whole machine.

Before you start

These are workflows you can try, not adoption claims. Install TSLink. 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:

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:

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:

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:

{"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 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:

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. To control TSLink itself remotely, use its separate opt-in remote MCP control plane.

Access a database over raw TCP

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

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, connect an existing local model, or check app health and uploads. 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.