Browsey

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.

Features

• 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 browsey and go

PWA Install

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.

Quick Start

Run directly with bunx — no installation needed:

bunx browsey start .

Or install globally:

bun install -g browsey
browsey start .

Usage

# 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-qr

All commands work with bunx browsey too:

bunx browsey start ./photos --open

Options

| 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 |

API

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 |

Response format

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"
    }
  ]
}

Development

# 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

Tech Stack

• Bun - Runtime, bundler, and package manager
• TypeScript - Type safety
• Bun.serve - Native HTTP server
• Bun.Glob - Pattern matching
• Commander.js - CLI argument parsing