DirBeam

DirBeam turns any directory into a fast, private file browser. It runs as a Node.js CLI and serves a responsive Preact SPA to desktop and mobile browsers.

npx dirbeam

The terminal shows local and LAN URLs plus a QR code. Scan the QR code from a phone to browse, upload, preview, edit, or download files.

Requirements

• Node.js 18 or newer
• A modern desktop or mobile browser

Usage

dirbeam [path]

-p, --port <port>         Preferred port; increments automatically if occupied
-h, --host <host>         Bind address (default: 0.0.0.0)
-r, --readonly            Disable upload, edit, move, rename, create, and delete
-a, --auth <user:pass>    Protect the server with HTTP Basic Auth
    --pin [code]           Use a supplied 4-digit PIN or generate one
-o, --open                Open the local URL in the default browser
    --hidden              Expose dotfiles (disabled by default)
    --show-hidden         Alias for --hidden
    --no-qr               Do not print a terminal QR code
    --help                Show help
-v, --version             Show the version

Examples:

# Share the current directory
npx dirbeam

# Read-only office share
npx dirbeam ./release --readonly

# Remote server with generated PIN
npx dirbeam /var/log --pin --port 9000

# Explicit credentials and local-only binding
npx dirbeam . --auth admin:change-me --host 127.0.0.1

DirBeam uses plain HTTP. A PIN or Basic Auth controls access but does not encrypt traffic. On an untrusted network or public server, place DirBeam behind HTTPS, a VPN, or an SSH tunnel.

Interface

• List and media-grid views with search, breadcrumbs, multi-select, and responsive layouts
• File/folder picker and drag-and-drop streaming uploads with progress
• Streaming individual downloads, Range requests, and on-the-fly ZIP archives
• Create, rename, move (including desktop drag-and-drop), and confirmed bulk deletion
• CodeMirror 6 editing for JavaScript/TypeScript, JSON, YAML, HTML, CSS, Python, Go, Rust, Bash, Markdown, and Dockerfiles
• Sanitized Markdown preview plus image, video, audio, PDF, and full-screen gallery viewers
• Automatic, light, and dark themes; touch-friendly controls and long-press menus

Development

npm install
npm run dev
npm run build
npm test

The Vite development server only builds the SPA. Run npm run build before starting the packaged server with npm start.

REST API

All endpoints use /api/v1:

| Method | Endpoint | Purpose | | ------ | ------------------- | --------------------------------------------------- | | GET | /fs/list?path= | List a directory | | GET | /fs/raw?path= | Stream a file, including byte ranges | | GET | /fs/content?path= | Read an editable text file | | PUT | /fs/content | Save { path, content } | | POST | /fs/upload | Multipart upload; path field must precede files | | POST | /fs/zip | Stream ZIP for { paths: [] } | | POST | /fs/action | Create, rename, move, or delete | | POST | /auth/pin | Validate a PIN and create a session |

Paths are always relative to the shared root. Traversal, symbolic links, NUL bytes, and hidden path segments (unless --hidden) are rejected.

Packaging

Only the CLI, server source, compiled SPA, license, and README are published. Development dependencies and client source are excluded from the npm tarball.

License

MIT

Security reports should follow SECURITY.md. Contributions are described in CONTRIBUTING.md.