vibefs

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

File 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.com

Agent 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 file
• vibefs.log — daemon log output
• config.json — configuration

License

MIT