@telepath-computer/fileserver

⚠️ Experimental. Early-stage software. The config schema, CLI, and API may change without notice between releases. Pin exact versions if you depend on it.

Small localhost HTTP sidecar that serves files from named disk mounts. Built as a sidecar for Television artifacts that need to fetch files from the local filesystem.

Status

v1. Read-only, GET-only, no authentication. Localhost by default.

Install

From npm:

npm install -g @telepath-computer/fileserver

From source:

git clone https://github.com/telepath-computer/fileserver
cd fileserver
npm install
npm run build
npm link

This installs a fileserver binary on your PATH.

Quick start

fileserver --mount vault=~/workspace/vault

Then:

curl http://127.0.0.1:8765/files/vault/README.md
curl http://127.0.0.1:8765/health

CLI

fileserver --mount <name=path> [--mount <name=path> ...] [--host <host>] [--port <port>]

Flags:

• --mount name=path — register a named mount. Repeat for multiple mounts. Required (at least one).
• --host — host/interface to bind. Defaults to 127.0.0.1.
• --port — port to listen on. Defaults to 8765.

Mount paths:

• Must resolve to a real directory at startup.
• May start with ~ or ~/ to refer to the invoking user's home directory. Other tilde forms (e.g. ~someone) are not expanded.
• Tildes that are not the first character of the path are treated literally.

Binding to a non-localhost address (for example --host 0.0.0.0) makes mounted files reachable from outside the local machine. v1 has no authentication beyond the mount boundary.

HTTP API

GET /files/<mount>/<relative-path>

Streams the file at <relative-path> inside the named mount.

Responses:

• 200 with the file contents. Includes an inferred Content-Type, Content-Length, and Access-Control-Allow-Origin: *.
• 404 if the mount is unknown, the file is missing, the resolved path is a directory, or path resolution would escape the mount root (traversal or symlink escape).
• 405 for any method other than GET.

GET /health

Returns 200 when the server is running. No body required.

CORS

All file and error responses include Access-Control-Allow-Origin: * so browser-based artifacts can fetch without per-origin setup.

Access boundary

The only access-control primitive is the named mount root.

• Each --mount name=path is resolved to its real absolute path at startup.
• For each request, the requested path is resolved and served only if the resolved path remains inside the mount root.
• Traversal attempts (..) and symlinks that escape the mount root are rejected with 404.
• Mounts that fail to resolve at startup cause the CLI to exit with an error.

What it does not do (v1)

• No writes, uploads, deletes, or moves.
• No directory listings or directory rendering.
• No file watching, change notifications, or caching.
• No authentication or per-file permissions.
• No range requests, conditional requests, or cache validation.

These may be revisited in later versions if a concrete use case needs them.

Use with Television

Run as a sidecar alongside the Television server:

fileserver --mount vault=~/workspace/vault --mount photos=~/Pictures

Television artifacts then fetch files from the sidecar:

http://127.0.0.1:8765/files/vault/notes/today.md
http://127.0.0.1:8765/files/photos/2026/cat.jpg

A future direction is to have Television launch and proxy extension processes like this one under its own routes. See the WIP proposal in the Television repo: docs/proposals/extension-process-mounts.md.

Development

npm install
npm run build
npm test
npm run check

Repository layout:

• src/cliArgs.ts — CLI flag parsing and mount config validation. Includes tilde expansion.
• src/cli.ts — CLI entrypoint. Wires CLI config into the app and starts the listener.
• src/app.ts — Express app construction, routing, headers, and status code translation.
• src/fileService.ts — Mount normalization, safe path resolution, and file lookup. No Express or CLI dependencies.
• test/ — TDD coverage for each module.
• docs/plan.md — v1 plan and design decisions.