Homeport docs

Everything you need to run, watch and share your local projects. Homeport runs on your own computer — no account, nothing to pay.

Install

Get the desktop app from the latest release — the download button on the home page picks the right one for your computer:

Or install from the terminal — the same app, without the “unverified developer” prompt:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/ferdousmikdad/Homeport/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/ferdousmikdad/Homeport/main/install.ps1 | iex

The app opens Homeport in its own window; closing the window (or Quit Homeport in the sidebar or ⌘K) stops it and every app it runs. Its data lives in ~/Library/Application Support/Homeport, %APPDATA%\Homeport or ~/.local/share/homeport.

Run from source

Nothing needs to be installed first. Download the ZIP from GitHub (or git clone it), then:

git clone https://github.com/ferdousmikdad/Homeport
cd Homeport
./run.sh            # macOS / Linux  (Windows: run.bat)

The first start sets everything up and then opens http://localhost:7777:

1. If your computer has Python 3.9+, Homeport uses it.
2. If not, it downloads a private copy of Python into the hidden .runtime/ folder — no admin rights, nothing system-wide.
3. It installs its few libraries into .venv/ in the same folder.

After that, starting is instant. Starting it again while it's running just opens the page. Options: --port 8000, --no-browser.

Adding apps

Click + Add app and pick what you want to run:

• Folder… — a project folder. If the folder holds several projects (say a site, a Node API and a PHP app), Homeport lists them all; tick the ones you want and add them in one go — each gets its own port, and they can start together.
• File… — a single file: an .html page (served with its folder, opening that exact page), a .php page, a Node .js script or a Python .py file (Streamlit apps too).

Homeport fills in the start command, port and project type. You can edit any of it. Homeport recognises Laravel, Symfony, PHP, Django, FastAPI, Flask, Streamlit, Node (Vite, Next, Nuxt, Astro, Angular, CRA, Express — npm, pnpm, yarn or bun), Deno, Rails, Go, Rust, Spring Boot, .NET, Docker Compose, Makefiles, shell launchers, Procfiles and static sites — including projects one folder down (like repo/app).

Generated commands install missing dependencies on the first start and pick a free port, so two Laravel apps don't both claim 8000.

Discover projects

Sidebar → Discover projects. Pick the folder that holds your projects (for example ~/Projects); Homeport lists every project inside, marks the ones already added, and adds the rest in one click.

Command palette

Press ⌘K (macOS) or Ctrl K (Windows/Linux) — or click Commands. Type a few letters and press ↵:

• stop api → Stop Shop API
• logs store → Logs: Storefront
• share store → Share Storefront publicly
• add redis → Add Redis service

Press / to filter the cards instead.

Named URLs

Every running app is also available at http://<app-id>.localhost:7777 — e.g. http://storefront.localhost:7777. All modern browsers and operating systems send *.localhost to your own computer, so there's nothing to configure. Live reload (WebSockets) keeps working.

Workspaces

Give related apps the same category (API, frontend, worker…). Hover the category heading and press ▶: Homeport starts them one by one in your order, each waiting until the previous one is up. ■ stops them in reverse. Drag cards to change the order.

Logs & restarts

Each app's output is saved to data/logs/, so logs survive restarts. Open them from the card (☰), search, download or clear. In Edit you can turn on auto-restart (bring crashed apps back), start with Homeport, and crash notifications.

Git on cards

Cards show the branch, uncommitted changes (●2) and commits to pull (↓1). •• → Pull & restart runs git pull --ff-only — it never merges or overwrites your work — and restarts the app if it was running.

Public share links

Start an app, click 🌐 Share, then Start sharing. You get a public https://…trycloudflare.com link within seconds — through Cloudflare's free, account-less Quick Tunnels.

• Password (optional): visitors see a password page first. Only a salted hash is stored.
• Expiry: 15 minutes to 24 hours, or never. The link also stops when you stop the app or quit Homeport.
• Works with any framework: visitors' requests carry the public address (X-Forwarded-Host/Proto), and leftover http://localhost:PORT links in pages, CSS, JavaScript and redirects are swapped for the public address.
• The first time, the dialog offers to install Cloudflare's open-source cloudflared (about 40 MB) into bin/.

Phone preview

•• → Open on phone… → Turn on. Scan the QR code with your phone's camera — the app opens on any device on the same Wi-Fi. Only that app is exposed, only until you turn it off or the app stops. The first time, your computer may ask to allow incoming connections.

Crash fixer

When an app stops, click Why? on its card. Homeport reads the latest run's log and explains the cause with one-click fixes:

Fixes are predefined actions — Homeport never runs text taken from a log.

Databases & services

Sidebar → Databases & services: PostgreSQL, MySQL/MariaDB, Redis, MongoDB and Mailpit (a test inbox for outgoing email). Each runs with the server already installed on your computer, or via Docker. They're normal apps in a Services group: start/stop, logs, free ports, data in data/services/.

•• → Copy connection URL or Copy .env settings gives you ready-made lines such as:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5433
DB_DATABASE=postgres
DB_USERNAME=postgres
DATABASE_URL=postgresql://postgres@127.0.0.1:5433/postgres

WordPress

Add a WordPress folder — a fresh download or a copy of a live site — and its card shows WordPress needs a database · Set up. One click:

1. creates (or reuses) a MySQL/MariaDB service and a database for the site;
2. points wp-config.php at it — your original is saved as wp-config.homeport-backup.php;
3. adds a small helper, wp-content/mu-plugins/homeport-url.php, so the site works on whatever address it's opened with: localhost, blog.localhost, your phone or a share link.

Then Import a database backup (.sql or .sql.gz from phpMyAdmin, your host or a backup plugin). Links saved with the old domain (e.g. https://theirsite.com) point to the current address automatically — nothing in the database is rewritten. Delete the helper file to go back.

Recipes

Teach Homeport a new kind of project with one JSON file — in recipes/ (shared via pull request) or ~/.homeport/recipes/ (just for you).

{
  "name": "Hugo",
  "match": { "all": ["archetypes|layouts|content"] },
  "requires": ["hugo"],
  "port": 1313,
  "command": "hugo server --port {port} --bind 127.0.0.1"
}

match.all / any / none check files (a|b = either, globs allowed); contains checks a file for a pattern; setup runs steps only when something is missing; command_windows overrides for Windows. See recipes/README.md.

Start at login

AI assistant (optional)

If you already use Claude Code, a chat bubble appears in the corner (⌘J / Ctrl J) that can diagnose and fix apps. Without it, the bubble stays hidden and everything else works the same.

Troubleshooting

The page looks broken after an update

Reload with ⌘⇧R / Ctrl Shift R.

Named URLs don't open in Safari

Use http://localhost:<port> from the card, or another browser; some older Safari versions don't resolve *.localhost.

“Port 8000 is used by …”

Another program holds the port. Use Kill & start (it shows exactly which process first) or change the port in Edit.

Windows: “Python was not found”

Just run run.bat again — it downloads a private Python automatically. If your network blocks GitHub downloads, install Python from python.org and tick “Add python.exe to PATH”.

Uninstall

Quit Homeport (Ctrl C in its window), remove start-at-login if you installed it, then delete the Homeport folder. Everything — the private Python, libraries, logs and service data — lives inside it.