Documentation

Overview

Ferrule is one binary that does two things at once: it's a reverse proxy that terminates TLS for hostnames you make up (like api.local), and it's a process supervisor that can start and restart your services directly. Both are driven by a single ferrule.toml file that lives in your project.

You don't have to use both halves. A service can be proxy_to only (something you start yourself), command only (something Ferrule starts, with no HTTP host attached), or both — Ferrule starts the process and routes a hostname to it.

Installation

Pick your platform. Every path ends with a single ferrule binary on your PATH.

brew install ferrule-dev/tap/ferrule
ferrule trust   # installs the local CA into your Keychain

curl -fsSL https://get.syntaxnet.org/install.sh | sh
ferrule trust   # uses ca-certificates / NSS depending on your distro

scoop bucket add ferrule https://github.com/ferrule-dev/scoop-bucket
scoop install ferrule
ferrule trust   # run from an elevated prompt

# requires Rust 1.75+
cargo install ferrule-proxy
ferrule trust

Quick start

1. Scaffold a config. Run this inside your project — it writes a ferrule.toml with one example service pointing at 127.0.0.1:3000.

   shellcopy

   ferrule init

2. Edit it. Add every service you run locally, following the configuration reference below.

3. Trust the local CA, once per machine.

   shellcopy

   ferrule trust

4. Start everything.

   shellcopy

   ferrule up

   output

   ferrule — 3 services, https on :443
   
     name     host          upstream            status      uptime
     web      app.local     127.0.0.1:5173      up          00:04:12
     api      api.local     127.0.0.1:4000      up (2xx)    00:04:12
     worker   —             node worker.js      up          00:04:09
   
     press q to quit · l to view logs · r to reload config

5. Open https://app.local in a browser. No certificate warning.

Configuration reference

One [server] table, and one [[service]] block per service.

[server]

[[service]]

CLI reference

Routing rules

Routing is host-first: Ferrule reads the Host header (or the TLS SNI, for HTTPS) and matches it against every configured host. Matching is exact — api.local does not also match www.api.local. If you need several, list several services.

Two services can share a host if their path_prefix values don't overlap. The longest matching prefix wins, so a more specific rule can sit alongside a catch-all:

[[service]]
name = "app-shell"
host = "app.local"
path_prefix = "/"
proxy_to = "127.0.0.1:5173"

[[service]]
name = "app-api"
host = "app.local"
path_prefix = "/api"
proxy_to = "127.0.0.1:4000"

Requests to app.local/api/orders go to app-api; everything else on app.local goes to app-shell.

Local TLS

The first time ferrule up runs with local_ca = true, it generates a root key and certificate under ~/.config/ferrule/ca (Linux/macOS) or %APPDATA%\ferrule\ca (Windows) — never shared, never uploaded. ferrule trust adds that root to your OS trust store: Keychain on macOS, the NSS database and ca-certificates on Linux, the Windows Certificate Store on Windows.

From then on, Ferrule issues a short-lived leaf certificate for every configured host, valid 90 days and renewed automatically on ferrule reload. Because each machine has its own root, trusting your CA never lets you (or anyone) intercept another machine's traffic — teammates each run ferrule trust once, locally.

Process supervision

A service with a command is started by Ferrule as a child process. Its fate is controlled by restart:

• never — run once; if it exits, it stays stopped and shows as exited in the dashboard.
• on-failure — restart only on a non-zero exit code or a failing health_check.
• always — restart on any exit, including a clean one.

Restarts are spaced by backoff, a "min..max" range: the delay starts at min and doubles on each consecutive failure until it hits max, then holds there. A process that stabilizes resets the delay back to min.

If health_check is set, the service isn't marked up until that path returns a 2xx — useful for a Node or Rails process that opens its port before it's actually ready to serve.

Observability

ferrule status prints the same table the dashboard shows, for scripting:

$ ferrule status
name     host          upstream          status      uptime
web      app.local     127.0.0.1:5173    up          01:12:03
api      api.local     127.0.0.1:4000    up (2xx)    01:12:03
worker   —             node worker.js    restarting  00:00:04

The same data is available inside the browser at https://ferrule.local/status — a host Ferrule reserves for itself and answers on every machine it runs on. Set log_format = "json" in [server] to get structured, line-delimited logs instead of the human-readable default, suitable for piping into whatever you already use to read logs.

Troubleshooting