stable .localhost URLs for
every dev service.

A local reverse proxy that gives your projects memorable hostnames. No more port numbers, no more localhost:3847. Just myapp.localhost.

Get Started View on GitHub
npm Downloads
GitHub Stars
0
Dependencies
2
Platforms
4
Packages
155
Tests

Why localias?

Everything you need for painless local development routing.

Stable URLs

Every project gets a memorable .localhost hostname that never changes, even across reboots.

myapp.localhost:1355

Auto Port Allocation

Ports are assigned automatically. No collisions, no manual configuration needed.

localias run

Framework Detection

Detects Vite, Next.js, Nuxt, Angular, SvelteKit, and Astro. Injects the right flags automatically.

framework: vite

Docker Compose

Wrap docker compose to auto-discover services, allocate ports, inject env vars, and register .localhost routes for every service.

localias compose -- docker compose up

TLS / HTTPS

Generate and trust local certificates. Access services over HTTPS with zero effort.

localias proxy start --https

Git Worktree Support

Branch names become URL prefixes. Review branches side-by-side in the browser.

feat-auth.myapp.localhost

Hot Reload Aware

Proxied services maintain hot reload and WebSocket connections transparently.

watching...

Stale Cleanup

Orphaned routes are detected and removed automatically. No manual housekeeping.

stale route pruned

Custom Aliases

Map any .localhost hostname to any service. Create shortcuts for frequently used routes.

localias alias set

Hosts File Sync

Optionally sync routes to /etc/hosts for system-wide resolution beyond the browser.

/etc/hosts synced

Plugin SDK

Extend framework support with a typed plugin interface. Build custom integrations.

@localias/plugin-sdk

Clean Architecture

Hexagonal design with zero coupling. Core has no Node.js imports. Everything is testable.

clean architecture

How It Works

Four steps from install to stable URLs.

01

Start the proxy

The proxy listens on a single port and routes all *.localhost traffic.

localias proxy start
$ localias proxy start
proxy listening on :1355
routing *.localhost traffic
02

Run your app

Wrap your dev command with localias. It spawns the process and registers a route.

localias run
$ localias run -- npm run dev
spawning: npm run dev
process started on port 3291
03

Auto-detect & register

The framework is detected, a port is allocated, and a .localhost route is registered.

auto-detect
framework: vite
name inferred: myapp
route: myapp.localhost:1355 → :3291
04

Access your app

Open the stable URL in your browser. It never changes, even if the port does.

browser
http://myapp.localhost:1355
stable forever — no port to remember

Routing Table

localias list
HOSTNAME PORT STATUS
myapp.localhost:1355 3291 running
api.localhost:1355 4102 running
docs.localhost:1355 5500 running

Works with Docker too

Wrap your Docker Compose command — localias discovers services, allocates ports, and injects env vars automatically.

docker-compose.yml
services:
web:
build: ./web
environment:
- PORT=${WEB_PORT}
api:
build: ./api
environment:
- PORT=${API_PORT}
localias compose
$ localias compose -- docker compose up
parsing docker-compose.yml...
discovered 2 services
injecting WEB_PORT=3291, API_PORT=4102
 
web.myapp.localhost:1355 → :3291
api.myapp.localhost:1355 → :4102
 
routes cleanup on exit (Ctrl+C)

Install localias

Global install required — localias runs a background proxy, so npx won't work.

Global Install
npm i -g localias
Global Install
pnpm add -g localias
Global Install
yarn global add localias
Global Install
bun add -g localias
Global Install
brew install hammadxcm/localias/localias

See It In Action

Real commands, real output.

Run a Dev Server

localias run
$ localias run -- npm run dev
framework: vite
port: 3291
ready at http://myapp.localhost:1355

List Routes

localias list
$ localias list
HOSTNAME PORT STATUS
myapp.localhost:1355 3291 running
api.localhost:1355 4102 running
2 routes registered

Named Mode

localias run --name
$ localias run --name api -- node server.js
name: api
port: 4102
ready at http://api.localhost:1355

Docker Compose Up

localias compose
$ localias compose -- docker compose up
parsing docker-compose.yml...
discovered 3 services
web → web.myapp.localhost:1355 (:3291)
api → api.myapp.localhost:1355 (:4102)
docs → docs.myapp.localhost:1355 (:5500)

Custom Compose File

localias compose -f
$ localias compose -- docker compose -f dev.yml up
parsing dev.yml...
web → web.myapp.localhost:1355 (:3291)
api → api.myapp.localhost:1355 (:4102)
2 services ready

Injected Env Vars

env vars
# Auto-injected per service:
WEB_PORT=3291
WEB_PORT_0=3291
API_PORT=4102
API_PORT_0=4102
DOCS_PORT=5500

Multi-Port Service

multi-port
# Service "api" exposes 2 ports:
api.myapp.localhost:1355 → :4102
1.api.myapp.localhost:1355 → :4103
API_PORT_0=4102 API_PORT_1=4103

Named Project + Force

localias compose --name
$ localias compose --name shop --force \
-- docker compose up
project: shop (forced)
web.shop.localhost:1355 (:3291)
api.shop.localhost:1355 (:4102)

Trust Certificates

localias trust
$ localias trust
generating CA certificate...
CA added to system keychain
browsers will trust *.localhost

HTTPS Mode

localias proxy start --https
$ localias proxy start --https
TLS enabled
proxy listening on :1355
https://myapp.localhost:1355

Custom Alias

localias alias
$ localias alias set dashboard myapp
alias: dashboard.localhost → myapp
$ localias alias list
dashboard → myapp

Get Route Info

localias get
$ localias get myapp
hostname: myapp.localhost:1355
port: 3291
pid: 48291
status: running

Hosts Sync

localias hosts
$ localias hosts sync
syncing 3 routes to /etc/hosts
127.0.0.1 myapp.localhost
127.0.0.1 api.localhost
127.0.0.1 docs.localhost

Before & After

Stop memorizing port numbers.

Without localias

bash
$ docker compose up
web-1 | listening on :3000
api-1 | listening on :8080
docs-1 | listening on :4000
 
# which port was the API again? 8080? 3000?

With localias

localias
$ localias compose -- docker compose up
 
web.myapp.localhost:1355 running
api.myapp.localhost:1355 running
docs.myapp.localhost:1355 running