Caddy: Web Server With Automatic HTTPS

What Caddy is

Caddy is an extensible server platform written in Go that uses TLS by default. Most developers know it as the web server and reverse proxy that obtains and renews HTTPS certificates on its own, but the README frames it more broadly: Caddy is a platform for running long-lived Go programs, where each "app" is a Go module loaded into a single process. Two apps, tls and http, ship in the standard build, and everything else, from reverse proxying to file serving, is built from modules on top of them.

Matthew Holt started the project in 2014 while studying computer science at Brigham Young University. According to the README it soon became the first web server to use HTTPS automatically and by default, and it now has hundreds of contributors. Caddy is a project of ZeroSSL, an HID Global company, and the name is a registered trademark: the maintainers ask that it be called "Caddy" or "the Caddy web server", not "Caddy Server" or "CaddyServer".

The audience is wide. Solo developers use it to put a site or an API behind HTTPS with a few lines of config and no separate certificate tooling. Platform teams use its JSON configuration and admin API to drive the server from other programs. Companies hosting customer domains use On-Demand TLS to issue certificates for names they do not know ahead of time.

How Caddy works

Nearly all of Caddy's configuration lives in one document rather than being spread across command-line flags, environment variables and config files. That document is JSON, Caddy's native config language. Config adapters convert other formats into that JSON, and the README lists the Caddyfile, JSON 5, YAML, TOML and NGINX config as possible inputs. The README describes the design as setting the actual values of the initialized types in memory, from HTTP handlers and TLS handshakes to the storage medium.

The primary way to configure a running Caddy is its admin API, which listens on localhost:2019 and is restricted to localhost by default. The caddy command wraps the same API calls, so even config files go through the API under the hood. Every API endpoint that loads or changes config is graceful, with zero downtime. The getting-started guide explains that during a reload the new config is started before the old one is stopped; if the new config fails, it aborts with an error and the old one simply keeps running.

The docs compare the two common workflows. JSON is easy to generate, exposes the full range of Caddy's functionality, allows partial config changes and can be exported. The Caddyfile is easy to write by hand and covers most of Caddy's functionality, but only supports whole-config changes. The guide recommends keeping a single source of truth and notes that most people use either JSON with the API or the Caddyfile with the CLI.

Automatic HTTPS is where Caddy differs most from older servers. For qualifying hostnames it obtains certificates from ZeroSSL and Let's Encrypt, keeps them renewed and redirects HTTP on port 80 to HTTPS on port 443. For localhost, internal names and IP addresses it runs a fully managed local certificate authority built on Smallstep libraries, and the first time it may ask for a password to install its root certificate into the system trust store. It supports the HTTP, TLS-ALPN and DNS ACME challenges. The DNS challenge needs no open ports but does need a DNS provider module and credentials, and Let's Encrypt requires it for wildcard certificates. Caddy instances configured with the same storage share certificates and coordinate certificate management as a cluster.

Key features

• Caddyfile: a short, human-friendly config format; a reverse proxy for a domain is two lines.
• Native JSON config and admin API: change any part of a running server over HTTP, with graceful, zero-downtime updates.
• Config adapters: write config in the Caddyfile, YAML, TOML or other formats and have it converted to JSON with caddy adapt.
• Automatic HTTPS by default: public certificates from ZeroSSL and Let's Encrypt, a local CA for internal names, and multi-issuer fallback.
• On-Demand TLS: obtains a certificate during the first TLS handshake for a server name it does not have yet, without listing domains in config; it must be restricted with an "ask" endpoint that approves each domain.
• Encrypted ClientHello (ECH): the docs state Caddy can generate, publish and serve ECH configurations automatically, hiding the site's domain name from the network.
• HTTP/1.1, HTTP/2 and HTTP/3: all supported by default.
• No external dependencies: the README says Caddy runs anywhere with no external dependencies, not even libc.
• Modular plugins: custom builds with extra modules are produced with the xcaddy builder tool.
• Built-in CLI shortcuts: caddy reverse-proxy and caddy file-server start a proxy or static server without writing any config.
• Claims of scale: the README says Caddy has served trillions of requests, managed millions of TLS certificates and scaled to hundreds of thousands of sites in production.

Getting started with Caddy

The README's simplest cross-platform install is to download the binary from GitHub Releases and put it in your PATH; the documentation lists package-manager and other install methods. If you install from a package manager, Caddy may already be running as a service, and the tutorial asks you to stop it first.

The reverse proxy quick-start assumes a backend on port 9000. A plaintext proxy from port 2080 needs no config file at all:

caddy reverse-proxy --from :2080 --to :9000

Drop the --from flag and Caddy serves the proxy on localhost over HTTPS with an auto-renewing local certificate:

caddy reverse-proxy --to :9000

For a public site, put the domain in a file named Caddyfile. The DNS records must point at the machine and ports 80 and 443 must be reachable for Caddy to get a publicly trusted certificate:

example.com

reverse_proxy :9000

Then run it from the same directory, and apply later edits without downtime with a reload:

caddy run
caddy reload

Serving a static folder is just as short; --browse shows a file listing when there is no index file:

caddy file-server --browse

To inspect the active configuration, query the admin API:

curl localhost:2019/config/

Building from source requires Go 1.26.0 or newer. These steps do not embed version information; the README points to xcaddy build for builds with version information or plugins:

git clone "https://github.com/caddyserver/caddy.git"
cd caddy/cmd/caddy/
go build

On Linux, a self-built binary that needs to bind to low ports can be given that capability with:

sudo setcap cap_net_bind_service=+ep ./caddy

Use cases

• Reverse proxy for app containers: front one or many services with HTTPS that provisions and renews itself.
• Static site hosting: serve a build directory with file_server and automatic certificates.
• HTTPS in development and on internal networks: the local CA issues trusted certificates for localhost, internal hostnames and IPs.
• Custom domains in a SaaS product: On-Demand TLS issues certificates when a customer's domain first connects, approved by an endpoint that checks your accounts database.
• Programmatic control: orchestration tools push JSON config through the admin API instead of templating files and restarting processes.
• Clustered deployments: several instances share a storage backend and coordinate certificate management between them.

How Caddy compares

Caddy competes with general-purpose web servers and reverse proxies such as NGINX, Apache httpd, Traefik and HAProxy. The README's own comparison is about configuration: it contrasts Caddy's single config document with servers whose settings are scattered across flags, environment variables and files, and it claims a level of control over in-memory configuration that other servers do not expose. The inclusion of an NGINX config adapter in the README's list of inputs signals that migration from NGINX is an expected path.

The practical difference most teams notice is certificate management. Setups built on NGINX or Apache httpd commonly pair the server with a separate ACME client; Caddy builds issuance, renewal, OCSP handling and HTTP-to-HTTPS redirects into the server itself. Teams that already have mature certificate tooling, or need a module that exists only for another server, should weigh that before switching.

Things to know before adopting Caddy

• License and trademark: the code is Apache-2.0, a permissive license. The name "Caddy" is a registered trademark of Stack Holdings GmbH.
• Protect the admin endpoint: the API on localhost:2019 controls the whole server; it is not your website and is restricted to localhost by default for good reason.
• Low ports: binding to 80 and 443 needs elevated privileges or the cap_net_bind_service capability on Linux.
• Caddyfile limits: some features are only reachable through JSON, and with a config adapter the only way to change config through the API is the /load endpoint.
• DNS challenge plugins: DNS provider support is a community effort and usually means a custom build with xcaddy.
• On-Demand TLS needs guardrails: without an "ask" endpoint anyone pointing a domain at your server could trigger certificate issuance, so restrictions are mandatory.
• Support: the README advises companies to secure a support contract through Ardan Labs before they need help; free community help is on the caddy.community forum, and the issue tracker is reserved for bugs and feature requests.

Project activity

As of October 2026 the repository has about 77,900 stars and roughly 5,100 forks. It was created on GitHub in January 2015, is written in Go, is licensed under Apache-2.0 and was receiving commits in October 2026. The source is at github.com/caddyserver/caddy, the project site and documentation are at caddyserver.com, and the documentation itself is open source in the caddyserver/website repository.