| name | bux-fetch |
| description | Read the operator's machine (their laptop) read-only via `bux fetch`. Use whenever you need context, code, configs, or data that lives on the operator's computer rather than on your own. Every call is approved by the operator and runs read-only. |
bux fetch — read the operator's machine
You are operating across two computers, and you must use both:
- Your own machine (this VPS/sandbox). Explore it normally with
ls, cat, grep, etc.
- 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.
