pre-alpha

GuidesRuntime

Serve an application

implemented Updated November 20, 2026 11 min read

From the project directory:

hinoki dev
hinoki serve

hinoki dev reloads on every change while you work; hinoki serve runs without reload, with the workers your settings ask for. Both read the application from project.application in hinoki.toml. To run another application, pass its target: module:app, such as hinoki dev notes.main:app. A function callable without arguments that returns an application (a factory) is also accepted.

Each worker imports the target, then opens what the application owns (database pool, modules) in its lifespan and closes it on shutdown. Importing your code never opens a connection. See database connection ownership.

Choose a server

Both commands run on Kiso, Hinoki's own Rust server, unless you choose Granian:

Kiso (default) Granian
What it is Hinoki's HTTP server in the native extension (Rust: hyper, tokio, rustls) A general-purpose ASGI server, installed with the server extra
Runs on the native lane Eligible routes skip Python routing and binding (details) Every request goes through the ASGI pipeline
Access log Kiso's own, with access_log_format, access_log_skip, server_timing Granian's
Hinoki middleware Yes; the route runs in Python instead of the native lane Yes, identical
ASGI wrapper around the app Not possible: there is no ASGI boundary Yes, run the wrapper with granian (metrics)
WSGI --interface wsgi: Python threads behind Kiso's listener, not native (WSGI) --interface wsgi

Choose per run with a flag, or per project in settings:

hinoki serve --server granian
# notes/settings.py
from hinoki import settings


class ProjectSettings(settings.AppSettings, prefix="NOTES_", dotenv=".env"):
    server: settings.ServerSettings = settings.ServerSettings(server="granian")

hinoki new --server granian (or the server question of hinoki new) writes the same choice to settings.toml; NOTES_SERVER__SERVER=kiso overrides it for one environment. What Kiso runs natively, its limits, signals and proxy handling are on Kiso server.

Set host, port and workers

They come from the application's server settings group; flags override them:

Setting Variable Default Flag
server.host NOTES_SERVER__HOST 127.0.0.1 --host
server.port NOTES_SERVER__PORT 8000 --port
server.workers NOTES_SERVER__WORKERS 1 --workers (serve)
server.runtime_threads NOTES_SERVER__RUNTIME_THREADS 1
server.backlog NOTES_SERVER__BACKLOG 1024
server.access_log NOTES_SERVER__ACCESS_LOG unset Unset logs in hinoki dev only (or whenever access_log_format is set); true or false decides for both
server.access_log_skip NOTES_SERVER__ACCESS_LOG_SKIP unset Kiso only: comma-separated paths the log leaves out (health checks); exact, or a prefix when the entry ends with *
server.server_timing NOTES_SERVER__SERVER_TIMING unset Kiso only: add a Server-Timing header (kiso;dur=3.2;desc="native": milliseconds the server took and the serving lane, with the same values as the access log's lane); unset means hinoki dev only
server.recent_requests NOTES_SERVER__RECENT_REQUESTS unset Kiso only: file that also receives each request as a JSON line, read by the recent_requests tool of hinoki mcp; rotated near 1 MiB
server.access_log_slow_ms NOTES_SERVER__ACCESS_LOG_SLOW_MS unset Kiso only: keep only answers at least this slow, in milliseconds
server.access_log_format NOTES_SERVER__ACCESS_LOG_FORMAT unset Kiso only: pretty, plain, json or logger. Unset is pretty on a colour terminal and plain otherwise
server.server NOTES_SERVER__SERVER kiso --server

The connection limits and timeouts (max_connections, header_read_timeout, body_read_timeout, write_timeout), native_dispatch, the TLS files and http2, and trusted_proxies are described under Kiso and in the settings table. Left unset, they are None in hinoki settings and Kiso applies its own defaults (for example 10000 connections and a 10-second header timeout), so that Granian can refuse the Kiso-only ones only when you set them.

dev always runs one worker with reload. hinoki settings shows what is in effect (Inspect an application).

Before serving a deployment, narrow allowed_hosts to the names it answers to (NOTES_ALLOWED_HOSTS=app.example.com). While it is the default * and debug is off, each worker logs allowed_hosts is '*' and debug is off: ... at startup, on every server.

Settings that apply to one server only

hinoki serve refuses a setting the chosen server cannot honour, by name, and exits with status 2; it never ignores it or falls back to the other server.

Setting Kiso Granian
host, port, workers, runtime_threads, backlog, access_log, trusted_proxies, request_id_header, trust_request_id, tls_cert_file, tls_key_file, http2 applied applied
max_connections, header_read_timeout, body_read_timeout, write_timeout, native_dispatch, access_log_format, access_log_skip, access_log_slow_ms, recent_requests, server_timing applied when set refused when set

If the native extension of a build has no Kiso, --server kiso fails with an error that says so.

Optional startup probe

Hinoki(startup_url="/health") reserves one public, fixed GET/HEAD endpoint and returns {"status":"ok"} after that worker's lifespan startup has completed. The setting is off by default. Its path must be a literal ASCII path; query strings, fragments, parameters, percent escapes and dot segments are rejected. It must not match an application route or an enabled OpenAPI/docs path. The endpoint is not an application route and does not appear in OpenAPI or generated CRUD/MCP tools.

This is a startup probe, not a general readiness or liveness check. A 200 says that startup completed (and, on Kiso, its request wake reader was installed); it does not check database availability, downstream services, request capacity, or whether the Python event loop continues to make progress. It answers independently of the Python request queue when Kiso can apply the response directly. Before readiness it returns 503 not_ready; during shutdown readiness is cleared before graceful draining begins.

ASGI/Granian and WSGI answer it in the Python pipeline after host, CORS and HTTPS-redirect checks. Kiso checks host restrictions, answers CORS preflights and redirects plain HTTP requests on its Tokio thread before it considers the probe. GET and HEAD negotiate application/json and validate query syntax; other methods return 405 with Allow: GET, HEAD, unless CORS answers a preflight first. WSGI reads request bodies before the pipeline, so its body-size behavior differs from Kiso for a body sent to this GET/HEAD endpoint. WSGI also starts lazily on the first request and uses its adapter-level 503 if startup fails. Since WSGI exposes a decoded PATH_INFO rather than the raw request path, percent-encoded aliases may be indistinguishable from the literal probe path there.

Other runners

dev and serve are conveniences. The application is a plain ASGI app, so any ASGI server can run it directly; the server settings group is then ignored, because only hinoki serve applies it:

granian --interface asgi notes.main:app

Metrics and tracing

Hinoki ships no metrics registry, exporter or tracing integration, and no health route besides the optional startup probe. On an ASGI server the application is a plain ASGI callable, so wrap it with the instrumentation you already use, or with a few lines of your own:

# notes/metrics.py
import time


class Timing:
    """Report each request's method, status and duration to ``record``."""

    def __init__(self, app, record):
        self.app, self.record = app, record

    async def __call__(self, scope, receive, send):
        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return
        started, status = time.monotonic(), None

        async def watch(message):
            nonlocal status
            if message["type"] == "http.response.start":
                status = message["status"]
            await send(message)

        try:
            await self.app(scope, receive, watch)
        finally:  # status stays None when the request was aborted before a response began
            self.record(scope["method"], status, time.monotonic() - started)


from notes.main import app as notes_app

app = Timing(notes_app, record=my_metrics.observe)  # serve with any ASGI server

What this measures is the time from the ASGI call to the last byte handed to the server, not what a client perceives. Keep method and status as labels; do not label by scope["path"] (it holds ids and has unbounded cardinality), the request ID (it is for correlating logs: logging.include_request_id adds it to each Hinoki log line) or the caller. Hinoki does not currently expose the matched route template to a wrapper, so per-route metrics need an application-level counter inside the handler or a gap report so a hook can be designed.

Kiso has no ASGI boundary, so this wrapper does not apply to it and it has no instrumentation seam today. Use the server's own limits and access log and the request log of your proxy, or serve with Granian when you need to wrap the application.

WSGI

ASGI is the intended way to serve Hinoki. When a deployment can only run WSGI, wrap the application:

# wsgi.py
from hinoki.wsgi import WSGIAdapter

from notes.main import app

wsgi_app = WSGIAdapter(app)
hinoki serve wsgi:wsgi_app --interface wsgi                    # Kiso
hinoki serve wsgi:wsgi_app --interface wsgi --server granian   # Granian

--interface wsgi (or server.interface = "wsgi" on the application the WSGIAdapter wraps) tells hinoki serve that the target is a WSGI callable rather than a Hinoki application; the default is asgi. The target may be a WSGIAdapter or any (environ, start_response) callable, but not a factory and not a Hinoki application (the error names WSGIAdapter). A project whose server.interface is wsgi refuses an ASGI target unless you pass --interface asgi. granian --interface wsgi wsgi:wsgi_app still works for a deployment that runs Granian directly.

WSGI on Kiso

Kiso owns the listener and calls the callable from a fixed pool of Python threads (execution.sync_workers) with a queue of execution.sync_queue waiting requests; beyond both the answer is 503 with Retry-After: 1. This path is not native: the application, the environment and every response chunk are Python objects, and the request crosses the interpreter lock. Rust owns the sockets, TLS, the access log, the limits and the end of the response.

  • Request body. Read in full before the call, up to execution.max_body_bytes: 413 above it, 408 if it stalls, 400 if malformed. Kiso therefore answers 413 for a body Granian's WSGI interface would pass on (Granian has no limit).
  • Response. Streamed: the head goes out with the first piece, a slow client slows the application down (a bounded buffer), and a client that leaves makes the next write fail and closes the iterable. An exception before the head answers 500 with an empty body and the traceback in the log; after it, the stream is reset instead of ending as complete.
  • Timeout. execution.request_timeout bounds the time until the response starts (504). A running sync call cannot be stopped; it keeps its thread until it returns.
  • Applies: TLS and HTTP/2, access_log and access_log_format, server_timing, max_connections, header and body timeouts, --workers and graceful shutdown (lifecycle.shutdown_timeout).
  • Does not apply: the native lane (native_dispatch is refused), host, CORS and redirect policies of the server (a wrapped Hinoki application still applies its own), and trusted_proxies (refused: the client address is the TCP peer).
  • Lifespan. A plain callable has none. A WSGIAdapter starts its application's modules when the worker starts, not on the first request, and stops them on a graceful stop.

The adapter itself buffers its responses, so streaming reaches the client only from a plain callable. Its other specifics below apply on both servers.

The adapter drives the same ASGI callable on a background event loop that it owns, so routing, binding, access, errors, limits and the OpenAPI document behave as under ASGI. Specifics:

  • Startup is lazy under Granian (Kiso starts them with the worker). Modules (including the database pool) start on the first request of each worker process, so a pre-forking server can import the file in its master process. If startup fails, every request answers 503 with not_ready and the error is logged.
  • Shutdown runs on WSGIAdapter.close() or, otherwise, at interpreter exit. A server that kills workers without exiting normally skips it, as it would any atexit hook.
  • Async handlers run on the adapter's loop and sync handlers on the bounded executor, as under ASGI. Each WSGI server thread blocks for the duration of its request, so concurrency is the server's thread count rather than the event loop.
  • Bodies are buffered. Request bodies are read up to max_body_bytes plus one byte, so an oversized upload still answers 413. Responses are complete before they are sent; streaming responses are not available, and a client disconnect is not reported to the handler.
  • Paths. The server decodes the path once and the adapter passes it on without decoding again, so a client's %2520 reaches the handler as %20, as under ASGI. A percent-encoded slash (%2F) cannot be told apart from a real one in WSGI and is not available inside a path parameter. A bad Content-Length answers 400.
  • One protocol per process. Do not serve the same application object over ASGI and WSGI in one process; the adapter owns its own loop and module lifespan. Run two processes if you need both.

The path is checked against Kiso and Granian (--interface wsgi, with one and two workers) by a parity test, not against every WSGI server.

Errors and edge cases

  • error: X is neither an application nor a factory: the target names something else, for example an ASGI wrapper; run wrappers with granian.
  • error: Granian is not installed; install the server extra: run uv sync in a generated project (it depends on hinoki[server]), or use Kiso.
  • hinoki dev reloads with watchfiles, also part of the server extra, on either server; without it dev exits with that message and serve still works.
  • --workers outside the supported range is refused on Kiso; 0 means "use server.workers".
  • --interface wsgi with server.native_dispatch or server.trusted_proxies set on Kiso exits with status 2 and names the setting.
  • --interface wsgi with a Hinoki application, a factory or a non-callable exits with an error that points to WSGIAdapter.
  • A Kiso-only setting under --server granian exits with status 2 and names the setting.

See also