Fare Drive

Fare Drive is a Python CLI for turning one machine into a personal file host and connecting to it from another machine as a client. It supports local storage management, authenticated uploads and downloads, token-based access, share links, trash, storage limits, Cloudflare tunnel launching, and a small terminal dashboard called faretop.

Modes

• server: hosts the drive, keeps metadata, and serves the HTTP API
• client: logs in and transfers files to and from a Fare Drive server

Features

• Username/password login
• Access-token login without username/password
• Upload files and directories
• Download files and directories
• Share links for file downloads
• Delete to trash
• Storage limit enforcement
• Client sync listing
• Auto-sync pull mode with --output and --watch-seconds
• Cloudflare tunnel process launcher
• faretop terminal status dashboard
• Persistent client config in ~/.config/fare-drive/config.json

Project Layout

• src/fare_drive/cli.py: CLI entrypoint
• src/fare_drive/server.py: server commands and HTTP API
• src/fare_drive/client.py: client commands and TUI
• src/fare_drive/auth.py: password hashing and signed tokens
• src/fare_drive/config.py: local client config persistence
• tests/test_integration.py: integration coverage for the main feature set

Installation

This repo is set up to run well from a Python 3.12+ environment. If you are using Conda, activate your fare-drive environment first.

python -m pip install -e .

You can also invoke the CLI directly through the module:

python -m fare_drive.cli --help

Quick Start

1. Initialize server storage

fare-drive server init \
  --root /tmp/fare-drive-server \
  --username demo \
  --password demo-pass \
  --storage-limit-gb 5

This creates:

• /tmp/fare-drive-server/data
• /tmp/fare-drive-server/trash
• /tmp/fare-drive-server/.fare-drive/server.json
• /tmp/fare-drive-server/.fare-drive/sessions.json
• /tmp/fare-drive-server/.fare-drive/runtime.json

2. Run the server

fare-drive server run \
  --root /tmp/fare-drive-server \
  --host 127.0.0.1 \
  --port 8876 \
  --public-url http://127.0.0.1:8876

3. Log in from a client

fare-drive client login \
  --endpoint http://127.0.0.1:8876 \
  --username demo \
  --password demo-pass

4. Upload a file

fare-drive client put ./my-file.txt --remote-path docs/my-file.txt

5. Download it back

fare-drive client get docs/my-file.txt --output ./downloads

Server Commands

server init

Initialize a new drive root.

fare-drive server init --root <PATH> --username <USER> --password <PASS> [--storage-limit-gb 10]

server run

Run the API server.

fare-drive server run --root <PATH> [--host 0.0.0.0] [--port 8765] [--public-url https://your-url]

By default, server run now also tries to start cloudflared automatically. It uses:

• FARE_DRIVE_SERVER_LOCAL_URL or http://<host>:<port> for quick tunnels
• the returned Cloudflare public URL to populate server runtime state automatically
• TUNNEL_API_TOKEN or CLOUDFLARE_TOKEN for named tunnel auth only when you also provide FARE_DRIVE_SERVER_PUBLIC_URL or --public-url

If you want the HTTP server without starting Cloudflare, use:

fare-drive server run --root <PATH> --no-start-tunnel

server status

Print local server metadata.

fare-drive server status --root <PATH>

server faretop

Open a server-side terminal dashboard directly on the host machine.

fare-drive server faretop --root <PATH>

It shows:

• drive root
• drive status
• storage usage
• trash size and trash item count
• public URL
• cloudflared pid
• uptime

Press q to exit.

server issue-access-token

Create a signed endpoint token for client login without a password.

fare-drive server issue-access-token --root <PATH> [--endpoint <PUBLIC_URL>] [--expires-in 3600]

If --endpoint is omitted, Fare Drive will use the public_url stored in the server runtime state.

server start-tunnel

Start cloudflared in the background and persist the pid plus the public URL that Cloudflare exposes.

fare-drive server start-tunnel \
  --root <PATH> \
  --local-url http://127.0.0.1:8765 \
  [--cloudflared-bin cloudflared] \
  [--token-env TUNNEL_API_TOKEN]

Notes:

• If .env exists in the current working directory, Fare Drive will load it.
• TUNNEL_API_TOKEN is supported directly.
• The sample .env in this repo already uses TUNNEL_API_TOKEN.
• If no tunnel token is available, Fare Drive starts a quick tunnel with cloudflared tunnel --url ....
• Fare Drive watches the cloudflared log output and stores the public URL that Cloudflare returns.

Server .env Integration

The server can read its key settings from a .env file in the current working directory. CLI flags still win, but any omitted server-side values can come from environment variables.

Supported keys:

• FARE_DRIVE_SERVER_ROOT
• FARE_DRIVE_SERVER_USERNAME
• FARE_DRIVE_SERVER_PASSWORD
• FARE_DRIVE_SERVER_STORAGE_LIMIT_GB
• FARE_DRIVE_SERVER_HOST
• FARE_DRIVE_SERVER_PORT
• FARE_DRIVE_SERVER_PUBLIC_URL
• FARE_DRIVE_SERVER_LOCAL_URL
• FARE_DRIVE_CLOUDFLARED_BIN
• FARE_DRIVE_TUNNEL_TOKEN_ENV
• FARE_DRIVE_CLOUDFLARED_WAIT_SECONDS
• FARE_DRIVE_ACCESS_TOKEN_EXPIRES_IN
• TUNNEL_API_TOKEN
• CLOUDFLARE_TOKEN

Example:

FARE_DRIVE_SERVER_ROOT=/tmp/fare-drive-server
FARE_DRIVE_SERVER_USERNAME=demo
FARE_DRIVE_SERVER_PASSWORD=demo-pass
FARE_DRIVE_SERVER_STORAGE_LIMIT_GB=5
FARE_DRIVE_SERVER_HOST=127.0.0.1
FARE_DRIVE_SERVER_PORT=8876
FARE_DRIVE_SERVER_PUBLIC_URL=
TUNNEL_API_TOKEN=your-cloudflare-tunnel-token

If FARE_DRIVE_SERVER_LOCAL_URL is omitted, Fare Drive generates it automatically from FARE_DRIVE_SERVER_HOST and FARE_DRIVE_SERVER_PORT.

Client Commands

client login

fare-drive client login --endpoint <URL> --username <USER> [--password <PASS>]

client login-token

fare-drive client login-token --access-token <TOKEN>

client put

Upload a file or directory.

fare-drive client put ./local-file.txt --remote-path files/local-file.txt
fare-drive client put ./local-folder --remote-path folders/local-folder

client get

Download a file or directory.

fare-drive client get files/local-file.txt --output ./downloads
fare-drive client get folders/local-folder --output ./downloads

client delete

Move a file or directory into the server trash.

fare-drive client delete files/local-file.txt

client share

Generate a signed share token and a ready-to-open share URL.

fare-drive client share files/local-file.txt --expires-in 1800

Example response:

{
  "share_token": "...",
  "share_url": "https://your-public-url/s/..."
}

client status

Show live server status through the authenticated API.

fare-drive client status

client sync

List remote metadata:

fare-drive client sync

Mirror remote content into a local directory:

fare-drive client sync --output ./mirror

Repeat periodically for a simple auto-sync pull loop:

fare-drive client sync --output ./mirror --watch-seconds 30

client faretop

Open the terminal dashboard.

fare-drive client faretop

It displays:

• drive status
• storage usage
• upload and download byte counts
• connected clients
• uptime
• current endpoint

Press q to exit.

Config

Client config is stored at:

~/.config/fare-drive/config.json

Stored fields:

• endpoint
• username
• bearer_token
• access_token

Share Links

Share links are download-only and path-scoped. A share token can fetch only the file it was created for. It cannot upload, delete, create new shares, or inspect sync/status metadata.

Storage Behavior

• All server files live under <root>/data
• Deleted files move into <root>/trash
• Storage usage is measured against the configured byte limit
• Archive uploads are checked against uncompressed tar member sizes before extraction

Security Notes

• Passwords are stored as salted SHA-256 hashes
• Access tokens and share tokens are HMAC-signed
• Tar extraction is path-validated and uses safe extraction filtering
• Relative-path traversal such as .. is rejected

Testing

Run the integration suite from the local fare-drive environment:

python -m unittest -v tests.test_integration

The current suite verifies:

• server initialization
• server status
• username/password login
• endpoint-token login
• file upload
• directory upload
• file download
• directory download
• sync listing
• sync pull mode
• share link generation and download
• delete to trash
• storage-limit rejection
• tunnel launcher state update
• faretop startup and exit

Current Status

This repository now contains a working MVP with integration coverage for the main server and client workflows. It is a strong base for the next round of improvements, especially resumable large-file transfer, richer sync conflict handling, restore-from-trash commands, and a production-grade named Cloudflare tunnel setup.