dotnet-serve

dotnet-serve

A simple command-line HTTP server.

It launches a server in the current working directory and serves all files from that directory.

Get started

Install .NET and run this command:

dotnet tool install --global dotnet-serve

Start a simple server and open the browser by running:

dotnet serve -o

And with HTTPS:

dotnet serve -o -S

With a specific port (otherwise, it defaults to a random unused port):

dotnet serve --port 8080

Allow access from remote machines (defaults to loopback only). Use this if running inside Docker:

dotnet serve --address any

Usage

…

Tip: single letters for options can be combined. Example: dotnet serve -Sozq

Configuring HTTPS

dotnet serve -S will serve requests over HTTPS. By default, it will attempt to find an appropriate certificate on the machine.

By default, dotnet serve will look for, in order:

• A pair of files named cert.pem and private.key in the current directory
• A file named cert.pfx in the current directory
• The ASP.NET Core Developer Certificate (localhost only)

You can also manually specify certificates as command line options (see below):

See also this doc for how to create a self-signed HTTPS certificate.

.pem files

Use this when you have your certificate and private key stored in separate files (PEM encoded):

dotnet serve --cert ./cert.pem --key ./private.pem

Note: currently only RSA private keys are supported.

.pfx file

Use this when you have your certificate as a .pfx/.p12 file (PKCS#12 format):

dotnet serve --pfx myCert.pfx --pfx-pwd certPass123

Using the ASP.NET Core Developer Certificate

The developer certificate is automatically created the first time you use dotnet. When serving on 'localhost', dotnet-serve will discover and use it when you run:

dotnet serve -S

Reverse Proxy

dotnet-serve --reverse-proxy /api/{**all}=http://localhost:5000 will proxy all requests matching /api/* to http://localhost:5000/api/*.

The source path pattern uses ASP.NET routing syntax. See the ASP.NET docs for more info.

Multiple --reverse-proxy directives can be defined.

Reusing options with .netconfig

dotnet-serve supports reading and saving options using dotnet-config, which provides hierarchical inherited configuration for any .NET tool. This means you can save your frequently used options to .netconfig so you don't need to specify them every time and for every folder you serve across your machine.

To save the options used in a particular run to the current directory's .netconfig, just append --save-options:

dotnet serve -p 8080 --gzip --cors --quiet --save-options

After running that command, a new .netconfig will be created (if there isn't one already there) with the following section for dotnet-serve:

[serve]
	port = 8000
	quiet
	gzip
	cors
	header = X-My-Option: foo
	header = X-Another: bar

Note: multiple header, mime type mappings, and exclude-file entries can be provided as individual variables.

You can place those settings in any parent folder, and they will be reused across all descendant folders. Alternatively, they can be saved to global (user profile) or system locations. To easily configure these options at those levels, use the dotnet-config tool itself:

dotnet config --global --set serve.port 8000

This will default the port to 8000 whenever a port is not specified in the command line. You can open the saved .netconfig at %USERPROFILE%\.netconfig or ~/.netconfig.

The cert, key and pfx values, in particular, can be relative paths that are resolved relative to the location of the declaring .netconfig file, which can be very convenient.