Tailcat Probe
@sntxrr/tailcat-probev2026.10.03.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.
02Models
@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
03Stats
A
100 / 100
Downloads
2
Archive size
17.9 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
- License declared1/1earned
- Verified public repository2/2earned
Repository
https://github.com/sntxrr/swamp-tailcat04Platforms
05Labels