localias

Firefox does not trust the system certificate store by default on MacOS/Linux, which can cause certificate warnings for secure Localias aliases. You can enable system trust by following these steps:

1. Open Firefox and visit about:config.
2. Search for security.enterprise_roots.enabled.
3. Set its value to true.
4. Restart Firefox.

If you are using Firefox on Windows to browse to a server running in WSL, you must manually import the Localias root certificate via Settings > Privacy & Security > Security > Certificates > View Certificates > Authorities > Import... using the path provided by localias debug cert.

security.enterprise_roots.enabled = true

When running Localias inside WSL, the certificates are installed in the Linux VM's trust store but not the Windows host. To avoid certificate warnings in Windows browsers, you must manually install the Localias root certificate into the Windows certificate store using the debug cert --install command. This command requires administrator privileges.

localias debug cert --install

Localias supports mDNS (multicast DNS) for domains ending in .local. This allows you to broadcast your local aliases to your entire network, making it easy to test responsive websites from other devices like mobile phones.

To create a network-accessible alias, use the localias add command with a .local TLD. Note that when visiting a secure .local alias from another device, you may need to accept a certificate warning.

$ localias add frontend.local 8080
[added] frontend.local -> 8080
$ localias add http://insecure.local 8080
[added] http://insecure.local 8080

Localias acts as a proxy on ports 80 and 443. On Linux, you may encounter a permission denied error when trying to bind to these ports. To fix this, grant the localias binary the CAP_NET_BIND_SERVICE capability using setcap.

sudo setcap CAP_NET_BIND_SERVICE=+eip $(which localias)

You can install localias using Homebrew, Go, or Nix. Alternatively, you can download the binaries manually from GitHub releases.

Homebrew

brew install peterldowns/tap/localias

Golang

To run without installing:

go run github.com/peterldowns/localias/cmd/localias@latest --help

To install:

go install github.com/peterldowns/localias/cmd/localias@latest

Nix (flakes)

To run without installing:

nix run github:peterldowns/localias -- --help

To install:

nix profile install --refresh github:peterldowns/localias

Manual Download

Download the appropriate binary for your architecture from the GitHub releases page.

Localias can be run in GitHub Actions CI environments to test with URLs that mirror production setups.

Important Note on SSL: When running on Ubuntu-based GitHub Actions runners, you may encounter issues with self-signed SSL certificate handling due to how NSS databases and certificate stores are managed.

For a production-ready implementation that includes certificate warming, chromium testing with backoff mechanisms, and handling of NSS database edge cases, it is recommended to use the community-maintained GitHub Action: iloveitaly/github-action-localias.

To start proxying requests, you must run the proxy server. Note that running the server requires sudo privileges to edit /etc/hosts, install TLS root certificates, and bind to ports 80/443. Localias will prompt for your password via a subshell when needed.

Foreground Mode

Use run to start the server in the foreground. This is useful for seeing logs and stopping the server with Ctrl+C.

localias run

Daemon Mode (Background)

Use start to run the proxy server as a background daemon process.

localias start

Daemon Management

If running in daemon mode, use these commands to manage the process:

• localias status: Show the status of the daemon.
• localias reload: Apply the latest configuration changes to the running daemon.
• localias stop: Stop the daemon process.

The localias CLI is used to securely manage local aliases for development servers. It allows you to map secure hostnames (e.g., https://secure.test) to local development ports (e.g., http://127.0.0.1:9000).

Common tasks include managing individual aliases, controlling the proxy server daemon, and importing configurations.

# Add an alias forwarding https://secure.test to http://127.0.0.1:9000
localias set secure.test 9000

# List all aliases
localias list

# Start the proxy server as a daemon process
localias start

# Run the proxy server in the foreground
localias run

If you receive the error localias could not start successfully or if localias status shows the daemon is not running, another process is likely already using ports 80 or 443.

Common causes include:

• Another instance of localias running in a different terminal.
• A proxy server like Caddy, Nginx, or Apache running.

Use ps aux | grep -i localias to check for other Localias instances and lsof -Pn | grep -E '\*:443|\*:80' to identify which services are listening on those ports. You must stop the conflicting process before Localias can start.

$ ps aux | grep -i localias
$ lsof -Pn | grep -E '\*:443|\*:80'

To manually import the Localias root certificate (e.g., into Firefox on Windows/WSL), use the debug cert command to print the absolute path to the certificate file.

$ localias debug cert
/Users/pd/Library/Application Support/localias/caddy/pki/authorities/local/root.crt

Use the following commands to interact directly with your configuration file:

Configuration Format

The configuration file is a simple YAML map of <alias>: <port>. You can specify protocol preferences:

# Serves over both https and http
bareTLD: 9003

# Serves over both https and http
implicitly_secure.test: 9002

# Explicitly secure (https and http)
https://explicit_secure.test: 9000

# Explicitly insecure (http only)
http://explicit_insecure.test: 9001

localias set frontend.test 3000