A file preview server with time-limited access control, designed for AI agents to share local files with users via URLs.
Files are not accessible by default. Each file must be explicitly authorized with a TTL (default: 1 hour). The server starts automatically on the first allow call and shuts down when all authorizations expire.
| Agent interaction | File preview |
|---|---|
 |
 |
Install
With uv:
# Install globally uv tool install vibefs # Or run directly without installing uvx vibefs --help
Usage
Authorize a file
vibefs allow /path/to/file.py # http://localhost:17173/f/a3b7c2d1/file.py vibefs allow /path/to/file.py --ttl 300 # 5 minutes vibefs allow /path/to/file.py --head 50 # Only first 50 lines vibefs allow /path/to/file.py --tail 20 # Only last 20 lines
The daemon starts automatically if it's not already running.
Authorize a git commit
vibefs allow-git /path/to/repo abc1234 # https://files.example.com/git/a3b7c2d1 vibefs allow-git . HEAD # Current commit in current repo vibefs allow-git . HEAD --ttl 300
The commit is displayed as a web page with metadata, file list, and expandable diffs with syntax highlighting.
Manage authorizations
vibefs list # List active authorizations vibefs revoke <token> # Revoke a specific authorization
Server control
vibefs status # Check if daemon is running vibefs stop # Stop the daemon vibefs serve # Start server in foreground (for debugging)
Configuration
vibefs config set base_url https://files.example.com vibefs config get base_url # Default TTL for allow/allow-git (in seconds, default: 3600) vibefs config set file_ttl 43200 # 12 hours # Pygments syntax highlighting options vibefs config set pygments.style dracula # Theme (default: monokai) vibefs config set pygments.linenos true # Show line numbers (default: false)
Available styles: monokai, dracula, github-dark, one-dark, nord, solarized-dark, gruvbox-dark, and many more.
When base_url is set, the allow command outputs URLs using it instead of localhost:port:
vibefs allow /path/to/file.py
# https://files.example.com/f/a3b7c2d1/file.pyFile rendering
- Code and text files (
.py,.js,.md,.json, etc.) are rendered with syntax highlighting via Pygments. - Git commits are rendered with metadata, file list, and expandable diffs highlighted with Pygments.
- Other files are served with their original content type.
Deploy
vibefs listens on localhost:17173 by default. To make it accessible from the internet, use a tunneling service to map the local port to a public domain.
Cloudflare Tunnel
# Install cloudflared: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ # Quick tunnel (temporary public URL) cloudflared tunnel --url http://localhost:17173 # Named tunnel (persistent domain) cloudflared tunnel create vibefs cloudflared tunnel route dns vibefs vibefs.example.com cloudflared tunnel run --url http://localhost:17173 vibefs
Other options
- ngrok:
ngrok http 17173 - Tailscale Funnel:
tailscale funnel 17173 - frp, bore, or any TCP tunneling tool
After setting up the tunnel, configure the base URL so generated links use your public domain:
vibefs config set base_url https://vibefs.example.comAgent integration
To let an AI agent use vibefs, add instructions like the following to its system prompt or tool documentation:
You have access to `vibefs`, a file preview tool. When you want to share a file
with the user, run:
vibefs allow /path/to/file [--ttl SECONDS]
This prints a URL. Send the URL to the user — they can open it in a browser to
view the file. The link expires after the TTL (default: 1 hour).
Use this when:
- Showing code, logs, or config files
- Sharing generated output
- Any time a file is easier to read in a browser than in chat
State
All runtime data is stored in ~/.vibefs/:
vibefs.db— authorization records (SQLite)vibefs.pid— daemon PID filevibefs.log— daemon log outputconfig.json— configuration
License
MIT