How to Use Portless URLs

Portless provides human-readable local URLs for your environments. Instead of http://localhost:42100, access http://feature-auth.localhost.

Prerequisites

Node.js 20+ must be installed. Hako auto-installs portless via bun install -g or npm install -g on first use if the binary isn't found on your PATH. The portless proxy daemon is also started automatically.

Enable Portless

Add to your hako.yml:

portless: true

URL Scheme

Single service (or Docker mode): http://{branch-slug}.localhost

Multi-service (monorepo or bare mode with 2+ services): http://{branch-slug}-{service-name}.localhost

Example with branch feature/auth and services web and api:

• http://feature-auth-web.localhost
• http://feature-auth-api.localhost

Lifecycle

URLs are registered on hako start and hako new --start. They are deregistered on hako stop. On first registration, hako installs portless and starts its proxy daemon automatically.

Viewing URLs

# Human-readable output with per-service URLs
hako ports [branch]

# JSON output with portless_url and portless_urls fields
hako ports --json [branch]

For the full JSON schema, see the CLI reference.