---
name: tailnet-file-share
description: Deliver a local file to the user — as a native chat attachment (`grix_file_upload`) or as a tailnet download/preview link (`grix_file_link`). Trigger when the user asks to view, send, share, download, or export any file on this machine.
trigger: When the user asks to view, send, share, download, or export any file on this machine
---

# Tailnet File Share

When the user wants a file that lives on this machine (image, log, report,
build artifact, exported data, …), never paste its path or contents. Pick one
of two tools and hand over the result.

## 1. Choose the tool

| Scenario | Tool |
|---|---|
| The file should appear as a proper attachment in the chat — especially images or videos the user will look at inline; ≤ 50 MB | `grix_file_upload` |
| File > 50 MB, a clickable download link is enough, or it is an arbitrary local artifact | `grix_file_link` |

`grix_file_upload` uploads to the Grix platform; the attachment renders
natively (images/videos inline) with no tailnet or certificate involved.
Supports images, videos, documents, archives up to 50 MB per file.

`grix_file_link` serves the file over HTTPS from this machine's tailnet
address. The link is unreachable from the public internet, stays valid
indefinitely, and the user can reopen it any time — do not mention expiry.

## 2. Call it and relay the result

- `grix_file_upload`: `file_path` (absolute) and `session_id` (the current
  chat's session unless the user names another); optional `caption` and
  `reply_to_message_id`. The tool delivers the attachment — do not also send
  a link.
- `grix_file_link`: `file_path` (absolute); leave `ttl_ms` unset. Copy the
  tool's `markdown` field into your reply **verbatim**:
  - images (jpg/png/gif/webp/svg …) come back as `![filename](url)` and
    render as an inline preview;
  - everything else comes back as `[filename](url)` for download.

Do not print the raw file path and do not paraphrase the file contents.

If `grix_file_link` fails (e.g. Tailscale is not connected), tell the user the
local file path so they can retrieve it themselves.

## 3. If the link does not open (`grix_file_link` only)

Links open inside the Grix app with no setup. In a system browser
(Safari/Chrome) the device must trust this machine's root CA once: the tool
result includes `ca_install_url`. The first time you send a link to a user, or
whenever they report "won't open / certificate not trusted / not secure", send
`ca_install_url` with the per-device steps in
[references/certificate-trust.md](references/certificate-trust.md). That file
also explains why the CA does not cover the user's own self-hosted HTTPS
services.