Skip to content
BranchesTags

Repository files navigation

 _    _                      _   _           _
| |  | |                    | | | |         | |
| |__| | ___  _ __ ___   ___| |_| | ___  ___| |_
|  __  |/ _ \| '_ ` _ \ / _ \ __| |/ _ \/ __| __|
| |  | | (_) | | | | | |  __/ |_| | (_) \__ \ |_
|_|  |_|\___/|_| |_| |_|\___|\__|_|\___/|___/\__|

Turn your laptop into a web server in 3 minutes.

CI PyPI License: MIT Python 3.10+

HomeHost is an open-source CLI tool that lets you host websites and web apps directly from your laptop — no cloud account, no credit card, no DevOps degree required. It auto-detects your project type, configures Caddy as your web server, and optionally creates a free Cloudflare Tunnel so anyone on the internet can reach your site.

The 3-Minute Golden Path

# 1. Install
pip install homehost

# 2. (First time only) check your system
homehost setup

# 3. Point it at your project and serve
cd ~/my-website
homehost serve .

# You'll see:
#
#  ✓ Detected: Static HTML/CSS/JS (Found index.html)
#  ✓ Port: 8080
#
#  ╭──────────────── ✓  my-website is running ────────────────╮
#  │   Local:    http://localhost:8080                        │
#  │   Network:  http://192.168.1.42:8080  (same Wi-Fi)      │
#  │                                                          │
#  │   Press Ctrl+C to stop.                                  │
#  ╰──────────────────────────────────────────────────────────╯
#
#  [QR code for mobile access]

Want it public? Add --public:

homehost serve . --public

#  ╭──────────────── ✓  my-website is running ────────────────╮
#  │   Local:    http://localhost:8080                        │
#  │   Network:  http://192.168.1.42:8080                     │
#  │   Public:   https://proud-tiger-42.trycloudflare.com     │
#  ╰──────────────────────────────────────────────────────────╯

Share the public URL with anyone. It works immediately, with HTTPS, from any device.

Installation

macOS / Linux

pip install homehost

Windows

pip install homehost

Windows PATH note: If homehost isn't found after install, run:

python -m homehost --version

If that works, add Python's Scripts folder to your PATH:

# Find the Scripts path
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
# Then add that path to your System Environment Variables → PATH

Or install with pipx which handles PATH automatically:

pip install pipx
pipx install homehost

Requirements: Python 3.10+, macOS 12+ or Windows 10/11.

HomeHost automatically installs Caddy and cloudflared when you first run homehost setup.

Quick Start

Step 1 — Install

pip install homehost

Step 2 — Check your system (first time only)

homehost setup

This runs homehost doctor to verify your environment and show how to install Caddy and cloudflared if they're missing. Output looks like:

  ✓  python: Python 3.12.2
  ✓  internet: Internet reachable
  ✓  disk: 20.0 GB free
  ✓  node: Node.js 22.1.0
  ○  caddy: Caddy not found
     → Install: brew install caddy  (macOS)
     → Install: winget install CaddyServer.Caddy  (Windows)
  ○  cloudflared: not found (needed for --public tunnels)
     → Install: brew install cloudflared  (macOS)

Step 3 — Serve your project

cd /path/to/your/project
homehost serve .

HomeHost auto-detects your project type and starts the right server. Press Ctrl+C to stop.

Step 4 — Go public (optional)

homehost serve . --public

Creates a free https://*.trycloudflare.com URL (no account required). Share it anywhere.

Step 5 — Open the web dashboard

Navigate to http://localhost:9111 while a project is running. You'll find project status, request logs, and traffic graphs.

CLI Reference

homehost serve — the main command

homehost serve [PATH] [OPTIONS]
Option Default Description
PATH . (current dir) Project directory to serve
--port, -p auto (8080–8099) Port to listen on
--public off Start a free Cloudflare Tunnel for internet access
--type, -t auto-detected Force project type: static, flask, fastapi, django, nextjs, react, node
--name, -n directory name Override the project display name
--no-reload off Disable file-change auto-reload

Examples:

homehost serve .                              # serve current directory
homehost serve ~/my-site                      # serve a specific path
homehost serve . --public                     # with public tunnel
homehost serve . --port 3000                  # on a specific port
homehost serve . --type flask                 # force project type
homehost serve . --public --no-reload         # public, no auto-reload

All commands

Command Description
homehost serve [path] Main command. Detect, register, and start serving a directory.
homehost serve [path] --public Start with a free Cloudflare Tunnel (public internet access)
homehost setup Check system dependencies and show how to install missing ones
homehost doctor Detailed system diagnostics
homehost new <template> <name> Scaffold a new project from a starter template
homehost start [project] Start a previously-registered project by name
homehost stop [project] Stop a running project
homehost stop --all Stop all running projects
homehost restart [project] Restart a project
homehost status Table view of all registered projects and their status
homehost list Short list of all projects
homehost logs [project] Stream logs for a project
homehost logs [project] --follow Live-tail logs
homehost dashboard Open the web dashboard in your browser
homehost config Show global config
homehost config [project] Show a project's config
homehost tunnel [project] Start/stop public tunnel for a registered project
homehost uninstall Remove all HomeHost data and config
homehost update Update HomeHost to the latest version
homehost --version Print version

Starter Templates

Create a new project from scratch:

homehost new static my-portfolio    # HTML/CSS/JS starter
homehost new flask my-api           # Flask app
homehost new fastapi my-backend     # FastAPI app with auto-docs

Then serve it:

cd my-portfolio
homehost serve .

Supported Project Types

HomeHost auto-detects your project type — no config file needed.

Type Detected by How it's served
Static HTML index.html in root Python's built-in HTTP server (or Caddy if installed)
Flask requirements.txt contains flask flask run via gunicorn
FastAPI requirements.txt contains fastapi uvicorn main:app
Django requirements.txt contains django python manage.py runserver
Next.js package.json with next dependency npx next start
React package.json with vite or react-scripts npm start
Node.js package.json without a specific framework npm start

Override detection with --type:

homehost serve . --type flask

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Your Machine                             │
│                                                                 │
│  Your Files / App                                               │
│        │                                                        │
│        ▼                                                        │
│  ┌──────────────────────────────────────────────┐              │
│  │  Caddy (web server / reverse proxy)          │              │
│  │  - Serves static files                       │              │
│  │  - Proxies Flask / FastAPI / Node apps       │              │
│  │  - Security headers (CSP, HSTS, etc.)        │              │
│  │  - Rate limiting                             │              │
│  └───────────────────────┬──────────────────────┘              │
│                          │                                      │
│  ┌───────────────────────▼──────────────────────┐              │
│  │  cloudflared (optional, --public only)        │              │
│  │  - Encrypted outbound tunnel to Cloudflare   │              │
│  │  - No firewall ports opened                  │              │
│  │  - Free *.trycloudflare.com URL              │              │
│  └───────────────────────┬──────────────────────┘              │
│                          │                                      │
│  HomeHost CLI            │    Web Dashboard                     │
│  homehost serve .   ─────┘    http://localhost:9111             │
└─────────────────────────────────────────────────────────────────┘
                           │
                           ▼
                    Public Internet

The tunnel creates an outbound-only encrypted connection — your IP address is never exposed directly.

HomeHost vs. the Alternatives

HomeHost Ngrok LocalTunnel Vercel
Price Free Freemium Free Freemium
Runs on your machine ✅ ✅ ✅ ❌
HTTPS ✅ ✅ ✅ ✅
Custom domains ✅ via Cloudflare 💰 Paid ❌ 💰 Paid
Python apps ✅ ✅ ✅ ❌
Auto-detect project type ✅ ❌ ❌ ✅
Exposes your IP ❌ ✅ ✅ ❌
Open source ✅ MIT ❌ ✅ ❌

Troubleshooting

homehost: command not found (Windows)

Python's Scripts directory isn't in your PATH. Fix it:

# Option A — use python -m
python -m homehost serve .

# Option B — install with pipx (adds to PATH automatically)
pip install pipx && pipx install homehost

# Option C — find the Scripts path and add it to PATH manually
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

Caddy or cloudflared not installed

Run homehost setup — it will show the exact install command for your OS.

Port already in use

HomeHost auto-picks the next free port in 8080–8099. You can also specify one:

homehost serve . --port 9000

--public tunnel doesn't start

cloudflared must be installed. Run homehost setup to check. Install manually:

  • macOS: brew install cloudflared
  • Windows: winget install Cloudflare.cloudflared

Run the full diagnostic

homehost doctor

Contributing

git clone https://github.com/ParamChordiya/homehost.git
cd homehost
pip install -e ".[dev]"
pytest tests/unit/

See CONTRIBUTING.md for the full guide.

License

MIT — see LICENSE.

Made with care for developers who were tired of paying for hosting.
If HomeHost saves you time, consider giving it a ⭐ on GitHub.

About

Turn your laptop into a web server. Host websites from home with zero config.

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages