Portless.NET.Tool 2.1.0

<p align="center"> <img src="https://img.shields.io/badge/.NET-10.0-512BD4?logo=dotnet" alt=".NET 10" /> </p>

<h1 align="center">Portless.NET</h1>

<p align="center"> <strong>Stable <code>.localhost</code> URLs for local development — no more port numbers.</strong> </p>

<p align="center"> <a href="#quick-start">Quick Start</a> • <a href="#commands">Commands</a> • <a href="#configuration">Configuration</a> • <a href="#docker">Docker</a> • <a href="#development">Development</a> </p>

<p align="center"> <img src="https://img.shields.io/badge/.NET-10.0-512BD4?logo=dotnet" alt=".NET 10" /> </p>

What is Portless.NET?

Portless.NET is a dotnet tool that eliminates port conflicts in local development by giving every service a stable, named URL. Instead of remembering whether your API runs on localhost:3001, localhost:8080, or localhost:5000, you just use:

http://myapi.localhost

It runs a lightweight reverse proxy (powered by Microsoft YARP) on your machine, auto-assigns free ports to your apps, and routes named .localhost domains to them. Works with any backend — .NET, Node.js, Python, Go, Docker containers, and more.

Inspired by Portless (Node.js), rebuilt with .NET 10 + YARP for native Windows support, better performance, and first-class .NET integration.

Quick Start

# 1. Install the tool
dotnet tool install -g Portless.NET.Tool

# 2. Run your app with a name
portless run myapi dotnet run

# 3. Open in browser
# http://myapi.localhost

That's it. The proxy starts automatically on first use.

Features

• Named .localhost URLs — http://myapi.localhost instead of http://localhost:5000
• Automatic proxy management — proxy starts on demand, no manual setup
• Auto port allocation — free ports assigned automatically, no conflicts
• Multiple backends & load balancing — RoundRobin, FirstAlphabetical, PowerOfTwoStrategies
• Path-based routing — route /api to one service, /app to another on the same host
• TCP proxying — proxy databases and non-HTTP services (Redis, PostgreSQL, etc.)
• Static aliases — map names to external services and Docker containers
• HTTPS with auto certificates — https:// with generated certs, zero config
• HTTP/2 support — multiplexing, header compression, gRPC-ready
• WebSocket & SignalR — real-time communication through the proxy
• Config-as-code — portless.config.yaml for declarative route management
• Daemon mode — run as a systemd user service (Linux)
• Shell completion — bash, zsh, fish
• Hosts file management — sync/clean /etc/hosts entries
• Cross-platform — Windows 10+, macOS 12+, Linux (Ubuntu, Debian, Fedora, Arch)
• Framework detection — auto-injects PORT, ASPNETCORE_URLS, and more

Installation

From NuGet (recommended)

dotnet tool install -g Portless.NET.Tool

From Source

git clone https://github.com/SergioTenza/portless-dotnet.git
cd portless-dotnet
dotnet build Portless.slnx --configuration Release
dotnet pack Portless.Cli/Portless.Cli.csproj -o ./nupkg --configuration Release
dotnet tool install --add-source ./nupkg -g Portless.NET.Tool

Verify

portless --help
portless proxy status

Commands

Proxy Management

App Management

Static Aliases

Config-Based Routing

TCP Proxying

Certificate Management

Daemon Mode (Linux)

Hosts File

Shell Completion

Configuration

Create a portless.config.yaml in your project root:

routes:
  # Simple HTTP route
  - host: myapi.localhost
    backends: ["http://localhost:5000"]
    path: /api

  # Multiple backends with load balancing
  - host: frontend.localhost
    backends: ["http://localhost:3000", "http://localhost:3001"]
    loadBalancePolicy: RoundRobin

  # TCP proxy for databases
  - host: db.localhost
    type: tcp
    listenPort: 5432
    backends: ["localhost:5432"]

Then start all routes at once:

portless up

Config File Discovery

Portless searches for portless.config.yaml in the current directory and parent directories. You can also specify a custom path:

portless up -f ./deploy/local-routes.yaml

Docker

Portless.NET can be containerized alongside your services:

Dockerfile

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish Portless.Proxy/Portless.Proxy.csproj -c Release -o /app/publish

FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
WORKDIR /app
COPY --from=build /app/publish .
EXPOSE 1355
ENTRYPOINT ["dotnet", "Portless.Proxy.dll", "--urls", "http://0.0.0.0:1355"]

Docker Compose

version: "3.8"
services:
  proxy:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "1355:1355"
    volumes:
      - ./portless.config.yaml:/app/portless.config.yaml

  api:
    build: ./src/MyApi
    environment:
      - PORT=5000

  frontend:
    build: ./src/Frontend
    environment:
      - PORT=3000

Use with External Containers

# Start your containers
docker compose up -d

# Alias external services
portless alias api 5000
portless alias frontend 3000
portless alias redis 6379 --host docker-host

# Or use TCP proxying for databases
portless tcp postgres localhost:5432 --listen 15432

Architecture

  Browser / Client
        |
        v
  ┌─────────────────────────────────────┐
  │        Portless.NET Proxy           │
  │        (Kestrel + YARP)             │
  │        :1355 (HTTP) / :1356 (HTTPS) │
  │                                     │
  │  ┌───────────────────────────────┐  │
  │  │       Route Table             │  │
  │  │  myapi.localhost   -> :5024   │  │
  │  │  frontend.localhost -> :3001  │  │
  │  │  db.localhost (TCP) -> :5432  │  │
  │  └───────────────────────────────┘  │
  └──────────┬──────────┬───────────────┘
             │          │
        ┌────v───┐ ┌───v────┐
        │  API   │ │Frontend│
        │ :5024  │ │ :3001  │
        └────────┘ └────────┘

Tech Stack

Project Structure

portless-dotnet/
├── Portless.Core/              # Shared core logic (routing, ports, persistence)
├── Portless.Cli/               # CLI entry point (dotnet tool)
├── Portless.Proxy/             # YARP proxy server (Kestrel)
├── Portless.Tests/             # Unit tests (xUnit)
├── Portless.IntegrationTests/  # Integration tests (CLI, processes)
├── Portless.E2ETests/          # End-to-end tests (tool install, workflows)
├── Examples/                   # Sample apps (WebApi, SignalR, WebSocket, Blazor)
├── TestApi/                    # Test API for development
└── docs/                       # Documentation

Environment Variables

Development

Prerequisites

• .NET 10 SDK
• Git

Build

dotnet build Portless.slnx --configuration Release

Run Tests

# All tests
dotnet test

# By suite
dotnet test Portless.Tests/Portless.Tests.csproj                    # Unit
dotnet test Portless.IntegrationTests/Portless.IntegrationTests.csproj  # Integration
dotnet test Portless.E2ETests/Portless.E2ETests.csproj              # E2E

# With coverage
dotnet test --collect:"XPlat Code Coverage"

Pack & Install Locally

dotnet pack Portless.Cli/Portless.Cli.csproj -o ./nupkg --configuration Release
dotnet tool install --add-source ./nupkg -g Portless.NET.Tool

Manual Smoke Test

portless --help
portless proxy start
portless run testapi dotnet run --project TestApi
portless list
curl http://testapi.localhost
portless proxy stop

Contributing

Contributions are welcome! This project is under active development.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

Please ensure all tests pass before submitting:

dotnet test

Cross-Platform Support

License

This project is licensed under the MIT License — see the LICENSE file for details.

Credits

• Portless — Original Node.js project and design inspiration
• YARP — Microsoft's reverse proxy engine powering the routing
• Spectre.Console — Beautiful console CLI framework
• .NET community for feedback and support

<p align="center"> Built with ❤️ by <a href="https://github.com/SergioTenza">Sergio Tenza</a> and contributors </p>