Skip to content

README.md

Latest commit

 

History

History
174 lines (119 loc) · 4.44 KB

README.md

File metadata and controls

174 lines (119 loc) · 4.44 KB

Freeman

Freeman is an open-source, self-hosted, web-based REST API client — a lightweight Postman alternative you can run on your own server.

No desktop install. No data leaves your network. Your team accesses it from any browser.

Freeman screenshot

Features

  • Collections & folders — organise requests just like Postman
  • Collection variables — define {{BASE_URL}} once, reuse everywhere across the collection
  • Import / Export — full Postman Collection v2.1 compatibility; migrate in seconds
  • Auth helpers — Bearer token, Basic auth, and API Key support built in
  • Team accounts — super admin creates accounts; no self-registration
  • CORS-free — all requests are proxied server-side via Guzzle; no browser restrictions
  • Rate limiting — 60 requests/min per user on the run endpoint
  • Self-contained — SQLite database, no external services required

Requirements

Requirement Minimum
PHP 8.2+
Composer 2.x
PHP extension: pdo_sqlite required
PHP extension: openssl required

No Node.js, no npm, no build step. Tailwind CSS and Alpine.js are loaded from CDN.

Installing missing PHP extensions

Ubuntu / Debian

sudo apt install php-sqlite3

RHEL / Fedora

sudo dnf install php-pdo php-sqlite3

Windows — enable extension=pdo_sqlite in your php.ini.

macOS (Homebrew) — extensions are bundled with the php formula.

Installation

1. Clone the repository

git clone https://github.com/your-org/freeman.git
cd freeman

2. Run the install wizard

php artisan freeman:install

That's it. The wizard will automatically:

  1. Install PHP dependencies via Composer (if not already installed)
  2. Check all PHP extension requirements
  3. Copy .env.example → .env
  4. Generate a secure APP_KEY
  5. Create the SQLite database file
  6. Run all database migrations
  7. Prompt you to create your super admin account

3. Set your app URL

Open .env and update:

APP_URL=https://your-domain.com

4. Start the server

Development

php artisan serve

Then open http://localhost:8000 in your browser.

Production (recommended: nginx + php-fpm)

Point your web server's document root at the public/ directory and set the following in .env:

APP_ENV=production
APP_DEBUG=false

Updating

git pull
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:clear
php artisan cache:clear

Configuration

All configuration lives in .env. Key settings:

Key Description Default
APP_NAME Displayed in the browser tab Freeman
APP_URL Full public URL where Freeman is hosted http://localhost:8000
APP_ENV Set to production for live deployments production
APP_DEBUG Always false in production false
SESSION_LIFETIME Session timeout in minutes 120

User management

Only the super admin can create user accounts — there is no self-registration. Log in with your super admin credentials and go to Admin → Users.

New users are prompted to change their password on first login.

Collection variables

Use {{VARIABLE_NAME}} syntax in any URL, header, or request body. Variables are defined per-collection under Variables in the collection settings panel and are substituted at request time.

Import & Export

Freeman uses the Postman Collection v2.1 format for both import and export, making it straightforward to migrate existing Postman collections without any manual work.

  • Export — open a collection and click Export
  • Import — click Import in the sidebar and upload a .json file

Roadmap

Feature Status
Collections, folders, saved requests ✅ Done
Request builder (headers, body, auth) ✅ Done
Collection variables ({{VAR}}) ✅ Done
Import / Export (Postman v2.1) ✅ Done
Auth helpers (Bearer / Basic / API Key) ✅ Done
Rate limiting on request execution ✅ Done
freeman:install wizard ✅ Done
Environments & environment switching 🔜 v2
Request history log 🔜 v2
Pre-request & test scripts 🔜 v2
Sharing collections between users 🔜 v2

License

MIT — free to use, modify, and self-host.