Metadata-Version: 2.4
Name: vibefs
Version: 0.2.0
Summary: A simple, secure file preview service with time-limited URLs
Project-URL: Homepage, https://github.com/reorx/vibefs
Project-URL: Repository, https://github.com/reorx/vibefs
Author-email: reorx <novoreorx@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,cli,file-server,preview
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: bottle>=0.13.4
Requires-Dist: click>=8.3.1
Requires-Dist: pygments>=2.19.2
Description-Content-Type: text/markdown

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

## Install

With [uv](https://docs.astral.sh/uv/):

```bash
# Install globally
uv tool install vibefs

# Or run directly without installing
uvx vibefs --help
```

## Usage

### Authorize a file

```bash
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.

### Manage authorizations

```bash
vibefs list                 # List active authorizations
vibefs revoke <token>       # Revoke a specific authorization
```

### Server control

```bash
vibefs status               # Check if daemon is running
vibefs stop                 # Stop the daemon
vibefs serve                # Start server in foreground (for debugging)
```

### Configuration

```bash
vibefs config set base_url https://files.example.com
vibefs config get base_url
```

When `base_url` is set, the `allow` command outputs URLs using it instead of `localhost:port`:

```bash
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.
- 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

```bash
# 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:

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