Reads a file out of the guest. The response body is the file’s bytes.

Needs the member role despite being a read. path is an arbitrary read of the guest’s filesystem rather than a read of anything this platform models — /home/user/.ssh/id_rsa is one call — which is strictly more than a viewer is given anywhere else.

A whole file is capped at 64 MiB, and a Range is how you get past that. Without one this endpoint refuses anything larger with a 413, because the bytes cross the guest agent in chunks and one request holds that channel for as long as it takes. With one, the cap applies to the WINDOW you asked for rather than to the file, so a 2 GB build output is something you page through rather than something you cannot fetch.

A satisfied range answers 206 with a Content-Range giving the bytes you got and the file’s total length. You may get fewer bytes than you asked for — a window past 64 MiB is trimmed to it rather than refused, since you cannot know the limit before you ask — so read the Content-Range and ask again from where it ended. That is the paging loop, and it needs nothing else:

curl -H "Authorization: Bearer $MANDALA_KEY" -H "Range: bytes=0-1048575" \
  ".../files?path=/home/user/out.tar" -D - -o part-0
  -> 206, Content-Range: bytes 0-1048575/2147483648

Which end is trimmed follows the end you anchored: bytes=N- keeps its start and loses its far end, while bytes=-N keeps its END — an over-long tail is still the tail of the file, never the middle of it.

A range that names no byte the file has is a 416 whose Content-Range carries the real length. A file whose length the guest cannot report — a /proc entry, say — answers Accept-Ranges: none and ignores your Range, sending the whole thing with a 200; the status is how you tell. And the 413 you get for asking for a whole file that is too big names this header in its message, since that refusal is exactly when you need to know the option exists.

Requires the member role or higher.