A mobile-friendly web file browser CLI tool built with Bun.
Start a local web server to browse files from any device on your network - perfect for quickly accessing files on your computer from your phone or tablet.
- Mobile-first UI - Touch-friendly interface with large tap targets
- Dark theme - Easy on the eyes
- Copy path - One-tap copy of absolute file paths
- Ignore patterns - Filter out files/folders with glob patterns
- QR code - Scan to open on mobile instantly
- Bonjour discovery - API advertises itself on local network (
_browsey._tcp) - Zero config - Just run
browseyand go
Browsey is installable as a PWA when served over HTTPS (or localhost). If you want Add to Home Screen on a remote device, put Browsey behind a TLS-terminating reverse proxy.
Run directly with bunx — no installation needed:
bunx browsey start .Or install globally:
bun install -g browsey browsey start .# Serve current directory browsey start # Serve a specific directory browsey start ./photos # Custom ports browsey start -p 3000 --app-port 3001 # Open browser automatically browsey start --open # Allow file modifications (default is read-only) browsey start --no-readonly # Ignore patterns browsey start -i "node_modules,.git,*.log" # Show hidden files browsey start --hidden # All options browsey start ./my-folder -p 4200 --app-port 4201 -i "node_modules,.git" --hidden --open --no-readonly --no-qrAll commands work with bunx browsey too:
bunx browsey start ./photos --open| Option | Description | Default |
|---|---|---|
[path] | Directory to serve | . (current) |
-p, --port <port> | Port number | 4200 |
-h, --host <host> | Host to bind | 0.0.0.0 |
-i, --ignore <globs> | Comma-separated ignore patterns | - |
--open | Open browser automatically | false |
--no-readonly | Allow file modifications | false |
--hidden | Show hidden files | false |
--no-qr | Do not display QR code | false |
--no-bonjour | Disable Bonjour/mDNS API advertisement | false |
--no-https | Disable HTTPS | - |
--https-cert <path> | Path to TLS certificate (PEM) | ./certs/browsey.pem |
--https-key <path> | Path to TLS private key (PEM) | ./certs/browsey-key.pem |
Browsey exposes a simple REST API:
| Endpoint | Description |
|---|---|
GET /api/list?path=/ | List directory contents |
GET /api/file?path=/file.txt | Download a file |
GET /api/stat?path=/file.txt | Get file metadata |
GET /api/list?path=/
{ "path": "/", "items": [ { "name": "documents", "type": "directory", "size": 4096, "modified": "2024-01-15T10:30:00.000Z", "extension": null }, { "name": "photo.jpg", "type": "file", "size": 245678, "modified": "2024-01-14T08:20:00.000Z", "extension": "jpg" } ] }# Clone the repo git clone https://github.com/vforsh/browsey.git cd browsey # Install dependencies bun install # Run in dev mode bun run dev # Build bun run build # Link locally for testing bun link- Bun - Runtime, bundler, and package manager
- TypeScript - Type safety
- Bun.serve - Native HTTP server
- Bun.Glob - Pattern matching
- Commander.js - CLI argument parsing