Tailcat Probe
@sntxrr/tailcat-probev2026.10.14.1
01README
Probe a tailcat server (netcat over Tailscale's data plane, no control plane): ping for reachability and direct-vs-DERP path, perf for throughput/RTT/jitter, transfer for a scp round-trip, exec for a remote command. Every result is a fixed-size summary — no per-second samples, file bodies or command output — so it is cheap on a remote datastore. The tailcat address is a bearer credential: it is a sensitive argument, redacted from captured output, and persisted only as a fingerprint. Long-running modes (serve, forward, socks, browse, recv) are refused.
02Release Notes
Declare SPDX license (MIT) in manifest.
03Behaviors
@sntxrr/tailcat/probev2026.10.03.1tailcat_probe.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| target | string | Non-secret label for the server, recorded in every result. |
| tailcatBinary? | string | Path to the tailcat binary. |
| derpmapUrl? | string | Custom DERP map URL, for self-hosted relays. |
| timeoutSeconds? | number | Hard ceiling on any single tailcat run. |
fn ping(untilDirect?: boolean, timeoutSeconds?: number)
Disco-ping the server once (or until a direct path appears) and
| Argument | Type | Description |
|---|---|---|
| untilDirect? | boolean | Keep pinging until a direct (non-DERP) path is found; fail if none |
| timeoutSeconds? | number |
fn perf(udp?: boolean, direction?: enum, seconds?: number, parallel?: number, bitrate?: string, viaDerp?: boolean, pathTimeoutSeconds?: number)
Run a bounded throughput test and record a fixed-size summary:
| Argument | Type | Description |
|---|---|---|
| udp? | boolean | |
| direction? | enum | |
| seconds? | number | |
| parallel? | number | |
| bitrate? | string | Per-stream target bitrate, e.g. 50M. Unset: unpaced TCP, 1M UDP. |
| viaDerp? | boolean | Allow a relayed test. tailcat refuses this through Tailscale's shared |
| pathTimeoutSeconds? | number |
fn transfer(direction: enum, remotePath?: string, maxHashBytes?: number)
Send a local file to, or fetch one from, a server running
| Argument | Type | Description |
|---|---|---|
| direction | enum | |
| remotePath? | string | Path relative to the served directory. Empty sends to its root. |
| maxHashBytes? | number |
fn exec(command: array, user?: string, captureStdoutBytes?: number)
Run one non-interactive command over `tailcat ssh` and record its
| Argument | Type | Description |
|---|---|---|
| command | array | Remote command and arguments. Required: interactive ssh is refused. |
| user? | string | |
| captureStdoutBytes? | number | Store this many leading bytes of stdout. 0 stores only size and hash. |
Resources
ping(7d)— Reachability and path (direct or DERP) to one server
perf(30d)— Throughput, RTT and jitter summary of one perf run — no per-second samples
transfer(7d)— Size and hash of one file sent or received — never its body
exec(7d)— Exit code, size and hash of one remote command's output
04Previous Versions
2026.10.03.1
05Stats
A
100 / 100
Downloads
17
Archive size
18.0 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned
Repository
https://github.com/sntxrr/swamp-tailcat06Platforms
07Labels