Collection spec reference

Every field on the bin form, what it does on the customer's machine, and how the edges behave. The spec is baked into the script each collection link serves; the customer sees the full spec on the link page before running anything.

Title

Required; everything else is optional. Shown in your console and used to identify the bin. Not part of what the customer's script collects.

Description

Internal notes for you and (if the bin is team-scoped) your team. Never shown to the customer and never included in the served script.

Globs

File patterns expanded on the customer's host — e.g. /var/log/myapp/*.log — and, when a container name is set, expanded a second time inside that container. Literal paths without wildcards work too. Each matched file is copied to a temporary staging area, hashed (SHA-256), and listed in the manifest gate for the customer's review.

Edge behavior: a glob that matches nothing prints tracebin: warning: glob matched no files: <glob> and is skipped — it never fails the run. A matched-but-unreadable file is skipped with a permission denied reason (the script never uses sudo) and recorded in the manifest, so you see the skip and why. Inside a container, expansion streams files out via docker exec + tar, falling back to per-file docker cp when the image has no tar, and to literal paths only when the image has no shell.

Commands

Shell commands run on the customer's machine, each captured to its own output file (cmd_0.txt, cmd_1.txt, …) with exit code, duration, and timestamps recorded in the manifest. Commands run with the customer's permissions.

Edge behavior: each command gets 60 seconds; on timeout it is terminated and recorded with timed_out: true and exit code 124 rather than failing the run. A nonzero exit code is recorded, not treated as an error. Command output files upload with the run in addition to the files listed at the review gate — the commands themselves are disclosed on the link page and, for wrapped links, in the consent summary.

Run in container

The per-command checkbox routes that command through docker exec into the spec's container instead of running it on the host. If the container is unavailable (no docker, daemon down, not found, stopped), the command is skipped with the reason recorded in the manifest and printed to the customer — the rest of the run proceeds.

Container name

Names a Docker container to collect from. When set, the globs are also expanded inside this container and in-container commands become possible. The script runs on the host and uses the customer's existing Docker access; it never runs inside the container itself.

Edge behavior: the script distinguishes four unavailability cases with distinct messages — docker not installed, daemon not running, container not found, container stopped — and in each case skips container collection while host collection proceeds. Status is checked against a running container; a stopped container's files are not collected.

Customer run command (wrap mode)

When set, the generated one-liner becomes a wrapped run: the script shows the customer this command plus everything that will be collected, asks Run this command and collect automatically on completion? [y/N], runs the command with no timeout, and on exit collects and uploads automatically — the single up-front consent replaces the post-collection upload prompt. The command's own output is captured too (see output capture below).

Edge behavior: a nonzero exit from the wrapped command still collects — failure is the diagnostic case. Ctrl+C during the command abandons the run with nothing collected or uploaded. Container status is checked after the command exits, so a command may launch the container it collects from — but a foreground container that stops when the command exits will be reported stopped and skipped; the bin form warns about this when both fields are set, and the fix is to run the container detached. A plain link stays available as ?mode=collect-now, which skips the wrap entirely and collects immediately with the normal review gate.

Workload output capture

Wrap mode only. The wrapped command's stdout and stderr are captured, keeping the last N KB — configurable from 16 to 5120 KB, default 256. If output exceeded the cap, the captured file begins with a disclosure line stating that earlier output was truncated, and the manifest records truncated: true; output under the cap is kept whole with no truncation claim.

Include file inventory

When on, the run additionally records a names-only inventory — file names, paths, sizes, modification times, never contents — of the directories your wildcard globs point at (immediate children only, not recursive). Its purpose is diagnosing empty globs: when a pattern matches nothing, the inventory shows what actually exists there. Literal paths are deliberately not inventoried, so a spec entry like /tmp/app.log never causes an inventory of all of /tmp. The inventory is disclosed to the customer up front and appears in the run as a browsable listing.

Collection link expiry

Each generated link carries its own expiry: 24 hours, 7 days (default), or 30 days from generation. Expiry is enforced by the server — an expired link returns an error script and nothing else, and expiry mid-run stops remaining uploads. One deliberate exception: when a customer consents to a wrapped run, the token gets a 48-hour upload grant from that moment, so a long-running workload's eventual upload isn't cut off by a link that expired while it ran. The grant only extends tokens still valid at consent time — an expired link can't be resurrected — and never applies to starting new collections. Tokens cannot be revoked early in the beta; they stop working only by expiring. The bin page marks tokens amber within 24 hours of expiry, and generating a fresh link is one click. Links are single-bin scope: a token only ever reaches the bin that minted it.

Limits that apply to every run

• 500 MB per file, enforced both by the script and the server. Larger files are skipped with an explicit message, never truncated.
• 2 GB per run in total, enforced by the server; files past the cap are skipped and reported.
• Per-link rate limits (spec fetches, upload URL requests) return HTTP 429 when exceeded.