Quick Start

featherbit needs two YAML files to start: system.yaml (listener, timeouts, logging, admin API) and gateway.yaml (routes and policies). The repository ships working examples in the config/ directory, wired to a small echo backend used for development.

Run from Docker Hub

The fastest path — multi-arch images (amd64/arm64) are published to Docker Hub:

docker run --rm -p 8080:8080 -p 9090:9090 featherbit/featherbit

The image ships the example config baked in at /etc/gateway/; mount your own system.yaml/gateway.yaml over it for real use. Tags: latest (newest release), edge (tip of develop), X.Y.Z (pinned releases) — each also available with a -headless suffix (no embedded web UI, admin REST API only). See Deployment for compose and production setups.

Run locally

cargo build
cargo run -- --system-config config/system.yaml --gateway-config config/gateway.yaml

Both flags default to config/system.yaml and config/gateway.yaml, so from the repository root cargo run alone works too.

Once started, the gateway listens on two ports:

Port	Purpose
:8080	Data plane — client traffic matched against your routes
:9090	Admin API and embedded web UI (HTTP Basic Auth, default admin/admin)

The default gateway.yaml proxies /api/* to an echo backend on localhost:3000. Start it in another terminal so upstream calls succeed:

python dev/echo-backend/server.py

Run with Docker Compose

docker compose up

This starts the gateway (ports 8080 and 9090, with config/ mounted into the container) and the echo-backend — a minimal HTTP server that echoes the method, path, and headers it receives back as JSON. Environment variables in the compose file (ECHO_BACKEND_HOST, ADMIN_PASSWORD, ...) are interpolated into the YAML config via the ${VAR:-default} syntax.

Send a request

The default route matches path: /api/* and applies a policy that strips the /api prefix before forwarding to the echo backend:

curl http://localhost:8080/api/users

The echo backend answers with a JSON view of what it actually received — note the stripped path:

{
  "method": "GET",
  "path": "/users",
  "headers": {
    "host": "localhost:3000",
    "accept": "*/*"
  }
}

This makes it easy to verify exactly which path and headers your routing policy delivered to the upstream.

Open the web UI

open http://localhost:9090

Log in with the admin credentials (default admin/admin) to see the node-graph editor. Select the echo-api route in the sidebar to view the policy you just exercised as a visual graph.

Next steps

Continue with Your first route to add a route and policy of your own, or read Architecture to understand what happened between curl and the echo response.