@alloyfs/http

A typed Node and Bun client for the AlloyFS HTTP API. Browse, read, write and watch an export over HTTP, without hand-rolling fetch calls and status-code ladders.

bun add @alloyfs/http     # or: npm i @alloyfs/http

import { connect } from "@alloyfs/http";

const agent = connect({
  url: "http://127.0.0.1:7441",
  token: process.env.ALLOYFS_TOKEN,
});

const projects = agent.export("projects");

for await (const entry of projects.walk("src")) {
  console.log(entry.name, entry.size);
}

What it is

A wrapper over one HTTP API, not a second implementation of it. Every method is one request, the client holds no socket, and the types mirror the wire shapes exactly — mtime_ms, not mtimeMs, because a translation table between a client and its server is a thing that drifts.

It is not a mount. Mounts speak the binary protocol and give you a real drive letter or mount point; this is for dashboards, scripts and CI, where a drive would be the wrong tool.

What it does for you

The HTTP API is small and honest, and there are exactly four things worth having a client for:

• Paging — walk() follows the cursor so you never hold a directory in memory. See Listing a directory.
• Safe writes — the ETag from a read handed straight back to a write, so a concurrent edit fails loudly instead of vanishing. See Writing without losing edits.
• Large files — upload() chunks past the agent's 256 MiB request cap. See Files larger than a request.
• Batching — bulk() keeps per-path results instead of throwing on the first miss. See Batching many paths.

Next

• Install
• Your first request
• Enabling the API on the agent side