portd

portd runs local development services in the background, detects their listening ports, and routes http://<service>.localhost to them.

portd currently supports Linux. Service names must be lowercase hostname labels, such as api or web-client.

Installation

You need a Rust toolchain. portd uses port 80 for its local proxy, so that port must be available to your user.

Install from Git

cargo install --git https://github.com/malezjaa/portd.git

Install from a local checkout

git clone https://github.com/malezjaa/portd.git
cd portd
cargo install --path .

Build the release binary

cargo build --release
install -Dm755 target/release/portd ~/.local/bin/portd

Make sure ~/.local/bin is in your PATH.

On Linux systems that restrict ports below 1024, grant portd permission to bind port 80:

sudo setcap cap_net_bind_service=+ep "$(command -v portd)"

Run this command again after reinstalling or replacing the binary.

Quick start

Start and inspect services:

portd run api cargo run
portd run web -- pnpm dev
portd list
portd open api
portd logs api --follow
portd stop api

Use --print with open to print the URL without opening a browser:

portd open api --print

Project configuration

Create a starter configuration in the current directory:

portd init

Edit the generated portd.toml, for example:

[services.api]
command = ["cargo", "run"]
restart = "on-failure"

[services.api.health]
path = "/health"

[services.web]
command = ["pnpm", "dev"]

Start or stop all services in the file:

portd up
portd down

To generate instructions for a coding agent, run:

portd agent-init

Service behavior

• restart = "on-failure" retries a failed service up to five times. A service that runs for at least 30 seconds gets a fresh retry budget.
• Health checks treat HTTP status codes from 200 through 299 as healthy. portd list shows starting, healthy, or unhealthy.
• Logs are prefixed with [stdout] or [stderr]. Each log rotates at 10 MiB, with three archives retained.
• The daemon state directory is $XDG_STATE_HOME/portd or $HOME/.local/state/portd by default. Set PORTD_STATE_DIR or pass --state-dir PATH to override it.

Control the daemon directly when needed:

portd daemon start
portd daemon status
portd daemon stop

License

Licensed under the MIT License. See LICENSE.