Ceryx is an MIT-licensed, programmable HTTP and HTTPS reverse proxy built on NGINX OpenResty that runs in a single container and is driven at runtime by a JSON API, for teams that need host-based routing across many domains without restarting the proxy.

What it is

Ceryx is a reverse proxy and gateway listed in this registry under Infrastructure & Operations / Networking & Connectivity, with Python as its language and the MIT licence. It lives in the Docker and NGINX OpenResty ecosystem: the proxy layer is NGINX OpenResty running Lua, the project ships as a container, and its behaviour is steered by an HTTP JSON API on port 8080 alongside environment-variable configuration. The README describes a single container supporting tens of thousands of routes, with domain-based proxying or redirecting, and host-based routing for both HTTP and HTTPS.

The problem it solves is the friction between a static proxy configuration and a changing set of backend services. Instead of editing configuration and restarting the proxy to apply it, an operator posts a route — {"source": "app.example.com", "target": "http://app:8000"} — to POST localhost:8080/api/routes, and the change takes effect in real time without a restart. Route state lives in SQLite at /var/lib/ceryx/db.sqlite by default, and TLS comes automatically from Let's Encrypt, from operator-supplied certificates, or from a self-signed default certificate for hostnames that have none.

Key capabilities

• Host-based routing for HTTP and HTTPS, where each route is created by posting a source hostname and a target URL to POST localhost:8080/api/routes.
• Real-time configuration updates without restarts, so a route from echo.localhost to http://echo:5678 is live as soon as the API call returns.
• Automatic Let's Encrypt certificates or your own, with CERYX_LETS_ENCRYPT_CA selecting the ACME directory and CERYX_DISABLE_LETS_ENCRYPT turning issuance off.
• Client certificate authentication (mTLS), HTTP/2 and WebSockets, alongside per-route settings.
• Environment-variable configuration including CERYX_MAX_REQUEST_BODY_SIZE (default 100m), CERYX_DNS_RESOLVER (default 127.0.0.11, Docker's resolver) and CERYX_TLS_DEFAULT_CERTIFICATE / CERYX_TLS_DEFAULT_KEY.
• Domain-based proxying or redirecting at the scale the README claims for it: tens of thousands of routes from one container.

Who uses it and how

• Local development: docker compose -f 'https://github.com/withlogicco/ceryx.git#v1.0.0:docs/compose.example.yml' up -d starts Ceryx together with a sample echo service, and because *.localhost points at the machine, routing works with no DNS setup.
• Single-server deployments: the repository's compose.yml is started on a server, with CERYX_EXTERNAL_HTTP_PORT, CERYX_EXTERNAL_HTTPS_PORT and CERYX_EXTERNAL_API_PORT used when ports 80, 443 or 8080 are already taken.
• Deployment and CI workflows: route changes are issued from inside the running container with docker compose -p ceryx exec ceryx curl -X POST localhost:8080/api/routes, so a hostname can be provisioned by a script.
• Multi-domain environments: many hostnames proxied or redirected from one gateway rather than one proxy instance per service.
• Ceryx contributors work in the repository's dev container and run the suite with docker compose -f compose.test.yml run --rm test.

Getting started

Ceryx is installed and run through Docker Compose: the quick start uses docker compose -f 'https://github.com/withlogicco/ceryx.git#v1.0.0:docs/compose.example.yml' up -d to launch Ceryx and a sample echo service, while a server deployment uses the repository's compose.yml at the same tag. Deployment options and the full configuration reference are documented at ceryx.dev.

How it compares

Beyond NGINX OpenResty, which is the substrate it is built on, the facts behind this entry name no other reverse proxies and no paid products that Ceryx replaces. It therefore stands alone in this registry rather than being contrasted with named alternatives, and the only distinguishing facts available are its own: MIT licensing, a single container, and an API-driven configuration model.

When to use it — and when not to

A self-hoster must operate the container together with its state: the SQLite database at /var/lib/ceryx/db.sqlite holds the route table and needs to be kept and backed up, and automatic TLS depends on ACME issuance against Let's Encrypt unless it is disabled or replaced with supplied certificates. Teams that need the complete feature set from the repository alone should know that the README is short and defers the full API and configuration reference to ceryx.dev. Anyone who wants a statically file-configured proxy, or who does not run Docker, should look elsewhere, since the documented install path is Docker Compose rather than a native package.

docker compose -f 'https://github.com/withlogicco/ceryx.git#v1.0.0:docs/compose.example.yml' up -d

docker compose -p ceryx-example-echo exec ceryx curl -X POST localhost:8080/api/routes -H 'Content-Type: application/json' \
  -d '{"source": "echo.localhost", "target": "http://echo:5678"}'

$ curl http://echo.localhost
Hello from behind Ceryx

docker compose -p ceryx exec ceryx curl -X POST localhost:8080/api/routes -H 'Content-Type: application/json' \
  -d '{"source": "app.example.com", "target": "http://app:8000"}'

docker compose -f 'https://github.com/withlogicco/ceryx.git#v1.0.0:compose.yml' up -d