Bux Fetch

bux fetch — read the operator's machine

You are operating across two computers, and you must use both:

1. Your own machine (this VPS/sandbox). Explore it normally with ls, cat, grep, etc.
2. The operator's machine (their laptop) — reachable only through bux fetch. This is where the operator's real code, configs, notes, and data usually live.

Do not assume everything you need is on your own machine. A large fraction of the useful context — the project the operator is actually working on, their local files, their configuration — exists on their laptop, not yours. When a task refers to "my project", "my files", "the repo on my machine", or anything you can't find locally, reach for bux fetch before concluding the information doesn't exist.

What it is

bux fetch asks the operator's laptop to perform a read-only operation. Each request is shown to the operator, who approves or denies it; approved requests run with read-only primitives (there is no way to write, edit, delete, or execute anything on their machine).

bux fetch list <path>             # like `ls` on the operator's machine
bux fetch read <path>             # like `cat` (text files; large files are truncated)
bux fetch grep <pattern> <path>   # like `grep -rn` (regexp, recursive, read-only)
bux fetch get  <path> [dest]      # copy a file from the operator's machine to here

Examples:

bux fetch list ~/Projects
bux fetch read ~/Projects/app/README.md
bux fetch grep "def main" ~/Projects/app      # find where something is defined/used
bux fetch get  ~/Projects/app/data.csv ./data.csv

grep takes a Go/RE2 regexp and searches a file or a whole directory tree, returning path:line:text. It skips binary files and noise dirs (.git, node_modules, …) and stops at 500 matches — so it's the cheapest way to locate something before reading.

Any absolute or ~-relative path is allowed — the operator decides per request.

Use it EFFICIENTLY — every call costs the operator a click

A human approves each request, so calls are slow, interruptive, and may be denied. Treat the operator's attention as the scarce resource:

• Locate before reading. Use grep to find which files matter (one approval searches a whole tree), then read only those — far cheaper than reading dozens of files to find one.
• Explore top-down. list a directory first, then do a few targeted reads — don't read dozens of files speculatively.
• Pull once. If you need to work over a file repeatedly, get it to your machine once and then use it locally — don't read the same file again and again.
• Ask for what you need, not what you might need. No scattershot reads "just in case".
• A denial is a normal answer. If a request comes back denied, do not retry it or rephrase and ask again — move on, and tell the operator what you were trying to do and why.
• Batch your reasoning, not the network. Decide the few files that actually matter, then request those.

What it is NOT

• It is not a way to modify the operator's machine. Writes/edits are impossible by design — don't try.
• It is not your own filesystem. bux fetch list ~ reads the operator's home, not yours.

Enabling it — tell the operator how

You don't set anything up; the operator does, from their laptop. If bux fetch reports it can't reach the operator, they're just not sharing right now. Don't retry in a loop — instead, tell the user exactly how to enable it:

To let me read files from your machine, run bux share on your laptop. It serves the approvals and auto-connects this box — nothing else to run.

If this box has never been provisioned for read access, they run bux setup <project> <box> once first (or bux share --setup <project> <box> to do both at once).

Then wait for them to do it — a failed bux fetch is a normal "not sharing yet" state, not an error to work around.