Guides

Raw file URLs

Fetch any single file from a machine (image repo) or a git repository with a plain URL — no clone, no boot, no SDK. Every file view in the web UI has a Raw button that opens the same URL these examples construct.

URL forms

Image repos (machines) resolve against the drive's active snapshot by default:

https://brintos.io/<owner>/<repo>/raw/<path>
https://brintos.io/<owner>/<repo>/raw/<path>?snapshot=<name>

Git repos take a ref — a branch, a tag, or a full 40-hex commit id — followed by the in-tree path:

https://brintos.io/<owner>/<repo>/raw/<ref>/<path>

When a branch name contains slashes the ref is matched longest-known-ref-first (the same rule GitHub uses), so /raw/feature/x/README.md resolves the branch feature/x if it exists. Percent-encode path segments that contain #, ?, or spaces. Directories are not listable — requesting a directory returns 404.

Redirects and caching

Branch and tag URLs are mutable: they answer with a short-lived 302 redirect to the immutable commit-id URL, re-checked within ~30 seconds of a push. The commit-id URL is the cacheable artifact — for public repos it is served with Cache-Control: public, max-age=31536000, immutable and cached at the CDN edge, so hotlinks and CI loops are fast after the first fetch.

$ curl -sIL https://brintos.io/alice/tool/raw/main/build.sh | grep -i '^location'
location: /alice/tool/raw/8a1f0c…e42d/build.sh

Always pass -L to curl (wget follows redirects by default) so the redirect is followed.

Image-repo files have no immutable form (snapshots are renameable), so public responses carry a short CDN cache instead — expect up to ~5 minutes of staleness on a public hotlink after you change a file. Private-repo responses are never cached (private, no-store).

Authentication

Public repos need no credentials. For private repos, pass a personal access token as a bearer header:

curl -L -H "Authorization: Bearer <token>" \
  https://brintos.io/you/secret-repo/raw/main/config.yaml

wget --header="Authorization: Bearer <token>" \
  https://brintos.io/you/machine/raw/etc/hostname

In a browser, your session cookie works — clicking Raw in the file viewer just works. Requests without access get a 404 (not 403): the existence of a private repo is itself private.

Response headers

Header	Behavior
`Content-Length`	Always present, so progress bars and resumers work.
`ETag`	Strong tag (the blob id for git files) — conditional GETs are free.
`Content-Type`	By file extension, falling back to `application/octet-stream`. HTML, SVG, and XML are served as `text/plain` (they never render on this origin).
`X-Brintos-Raw-Source`	`image` or `git`, for debugging which path served you.

Ranges and resume

Image-repo files support byte ranges (Accept-Ranges: bytes) — wget -c resumes an interrupted multi-GB download natively.
Git files do not (Accept-Ranges: none); a Range request gets the full 200 response. Interrupted downloads simply restart.

Cold starts and limits

Raw files are served by the same long-lived edge service that backs git and machine storage. If nothing has touched the repo recently, the first byte can take 10–30 seconds while the repo is mounted — wget and curl's default timeouts handle this fine; don't set an aggressive --max-time on the first fetch. Warm repos serve in milliseconds.

Heavy automated sweeps across many cold repos are throttled: expect 429 or 503 with a Retry-After header — back off and retry. A 504 with an X-Raw-Reason header means a mount or first-byte deadline fired rather than a silent hang.

Raw URLs serve file bytes only — no directory listings, and served content never executes on the brintos.io origin. For programmatic tree walks use the API; for whole-repo work, git clone or brintos-fs.