Skip to content
Hoplite

Begin typing to search this documentation.

Hoplite

Hara application server built directly into Nginx.

Nginx + Hara · one application server

Your application, directly inside Nginx.

Hoplite packages Hara routes, worker-local execution, service lifecycle, and provider-neutral transport into one refined server. Choose a target below and bring a real endpoint online.

Launch the starter →See measured speedDocumentationSource ↗
Runtime
Nginx + embedded Hara
Artifact
Executable or OCI image
Platforms
macOS and Linux

01 · First application

Choose where it runs.

One endpoint, one published runtime, and no source checkout. Switch targets to get the exact path from install to first response.

app.hal14 lines
(ns app
  (:require [hoplite.core :as h]))

(defn hello [_]
  {:status 200
   :headers {"content-type" "text/plain"
             "x-hoplite" "true"}
   :body "Hello from Hoplite\n"})

(def app
  (h/app
    {:name "hello"
     :resources
     [["/hello" {:get {:handler #'hello}}]]}))

Fastest start

Run the published image.

Install and run
docker run --rm -p 8080:8080 ghcr.io/greenways-ai/hoplite:latest
Verifycurl -i http://127.0.0.1:8080/hello

The image already contains Hoplite and the starter application.

GET/hello
STATUS200 OK
HEADERx-hoplite: true
BODYHello from Hoplite

02 · Equivalent-payload benchmark

Hoplite against raw Nginx.

Both targets use the same Nginx release and response contract. The benchmark validates status, content type, the stable x-hoplite header, and the exact 19-byte body before it accepts any measurements.

PayloadHello from Hoplite\n
Body19 bytes
Response identitySHA-256 matched
Load4 threads · 128 connections · 20s

Requests / second

Hoplite server43,436
Plain Nginx48,446
Hoplite delivers 89.7% of the raw Nginx request rate in this sample.

p50 latency

Hoplite server2.72 ms
Plain Nginx2.42 ms
Median request latency under the same thread and connection load.

p99 latency

Hoplite server9.57 ms
Plain Nginx8.70 ms
Tail latency from the same alternating-round wrk sample.

Peak memory under load

Hoplite server91.2 MiB
Plain Nginx11.9 MiB
Highest container memory sample observed while each target was loaded.

Hoplite server

Runtime executable
31.6 MiB
Deployment image
116.8 MiB
Idle memory
83.1 MiB

Plain Nginx

Runtime executable
4.5 MiB
Deployment image
89.6 MiB
Idle memory
3.7 MiB
All measured rounds
TargetRoundOrderRequests/sp50p99Peak memory
Hoplite1143,5752.71 ms9.74 ms86.9 MiB
Hoplite2243,3382.72 ms9.56 ms88.6 MiB
Hoplite3143,4362.72 ms9.57 ms91.2 MiB
Plain Nginx1248,4772.41 ms8.92 ms7.3 MiB
Plain Nginx2148,4462.42 ms8.68 ms9.9 MiB
Plain Nginx3248,2602.43 ms8.70 ms11.9 MiB
Recorded
Aug 11, 2026, 6:10 AM UTC
Commit
a5ee72d0
Runner
GitHub Actions 1000014881
CPU
AMD EPYC 7763 64-Core Processor · 4 logical
Rounds
3 per target
Scheduling
Target order alternates on every round

The previous all-in-one measurement has been retired. Until a validatedhoplite-server run completes, this page deliberately displays placeholders rather than carrying the old executable and memory values forward.

Reproduce the comparison

Build every target and validate both reports.

The orchestrator pins Hara, builds the slim server and comparison images, alternates HTTP target order, and rejects mismatched response contracts.

Hoplite benchmark suitesame response · validated reports
git -C ../hara checkout "$(cat packaging/hara-revision)"
HARA_ROOT=../hara bash packaging/scripts/run-benchmarks.sh benchmark-output
Runtime executable31.61 MiB/usr/local/bin/hoplite-server
Deployment image116.81 MiBhoplite-measure-31463659892-1-3072-server
Idle memory83.07 MiB+79.41 MiB versus raw Nginx
Resident processes5Nginx master and worker processes in the container
Nginx workers4Recorded after the server became ready

03 · Deployment footprint

What each stack occupies.

These are minimal deployment samples returning the same validated 19-byte response. They compare process and image shapes, not feature-equivalent web frameworks.

Hoplite server

Deploy image116.8 MiB
Idle memory82.7 MiB
Measured shape
Nginx + worker-local Hara runtime
Service surfaces
1 service surface
hoplite-server executable
31.61 MiB
What it represents
Routing and prepared Hara handlers in the Nginx lifecycle
Interpretation limit
Pre-1.0 interfaces; the alpha HBC/HBX contracts may still change

Nginx + JDK sample

Deploy image377.9 MiB
Idle memory40.5 MiB
Measured shape
Plain Nginx + JDK built-in HttpServer
Service surfaces
2 service surfaces
Sample JAR
<0.01 MiB
What it represents
A minimal JDK runtime deployment envelope
Interpretation limit
This is not a Ring, Spring, Quarkus, or Micronaut benchmark

Nginx + Python stdlib sample

Deploy image205.5 MiB
Idle memory12.9 MiB
Measured shape
Plain Nginx + ThreadingHTTPServer
Service surfaces
2 service surfaces
Sample source
<0.01 MiB
What it represents
A minimal Python standard-library deployment envelope
Interpretation limit
This is not a FastAPI, Flask, or Django benchmark

Nginx + ngx_http_lua sample

Deploy image222.7 MiB
Idle memory18.1 MiB
Measured shape
Debian Nginx + ngx_http_lua module
Service surfaces
1 service surface
Nginx executable
1.20 MiB
What it represents
A minimal in-process Lua response path
Interpretation limit
This is not the complete OpenResty distribution

Measured on GitHub Actions 1000014881 with 4 logical CPUs. Idle memory is the median of 12 samples per component.

Logical Docker image sizes are summed for multi-service stacks; shared registry layers may deduplicate in practice.

Minimal deployment-envelope samples returning one fixed response. The JDK and Python targets are standard-library servers, not framework benchmarks. The Lua target uses Debian ngx_http_lua, not a full OpenResty distribution.

The useful question is where each minimal serving envelope places its proxy, runtime, application artifact, processes, and resident memory—not whether every application in a language has one fixed size.

05 · Documentation

See what happens—and why.

Each section starts with a concrete operation, then explains the runtime or operational reason behind it. Use the example to enter; use the reference to be exact.

Start here · 5 guides

Getting started

Install the published runtime, generate a two-file application, and serve it.

First service
brew install greenways-ai/tap/hoplite
hoplite serve build --mode prod .
hoplite-server .
Why it matters

This is the shortest supported path from an empty machine to a real endpoint. It uses the packaged server rather than asking users to compile Hoplite or assemble a proxy stack.

Open section →
System model · 5 topics

Concepts

See how resources, operations and handler Vars become a worker-local router.

A route is data
["/hello"
 {:get {:name "hello"
        :handler #'hello}}]
Why it matters

The route stores a Var instead of calling the function while configuration is read. Hoplite can validate the resource tree, then resolve and compile the handler once when each Nginx worker starts.

Open section →
Operations · 9 guides

Guides

Build the parts that make an application useful: async work, application policy, OpenAPI, diagnostics and production operation.

Yield to Nginx
(defn delayed [_]
  (await (Host/call "nginx" "sleep" [25]))
  {:status 200 :body "resumed"})
Why it matters

When the handler awaits a host capability, the worker can resume other requests. Synchronous handlers stay on the direct path and do not pay for promise state they never use.

Open section →
Interfaces · 10 references

Reference

Look up the exact commands, project keys and public forms used by the current release.

Production contract
hoplite serve check .
hoplite serve build --mode prod .
hoplite verify .
hoplite inspect .
Why it matters

The reference is where examples become exact contracts. These commands validate the project, build the source-free production plan, verify its immutable bytes and inspect generated output without executing application source.

Open section →

05 · Current release

Published. Pre-1.0. Built in the open.

Hoplite 0.2.0 ships for Apple Silicon, Intel macOS, ARM64 Linux, and x86-64 Linux, with Homebrew and GHCR distribution. Interfaces remain intentionally pre-1.0 while the bytecode bootstrap and hosting contracts settle.

Release
0.2.0
Distribution
Homebrew · binary · OCI
License
Apache-2.0
Release and roadmap →