Skip to content

Install

pip install oxbrook

Requirements

  • CPython 3.14. The free-threaded build (python3.14t) is the primary target and runs several worker loops; the standard build runs one.
  • Linux, macOS or Windows. Wheels are published for both interpreter builds: x86-64 and ARM on Linux (manylinux 2.28) and macOS (11 or newer), and x86-64 on Windows. Elsewhere pip builds from the source distribution, which needs a Rust toolchain.

    Windows is a development platform here rather than a deployment one: the suites run on it on both interpreter builds, and everything works, but nothing is measured there and no benchmark on this site comes from it. A worker loop on Windows is a selector loop and so watches at most 512 sockets, which bounds what handlers on one loop may hold open — outbound connections, mostly — rather than the connections the server accepts. - Redis, only for durable topics: pip install oxbrook redis. - PyJWT, only for JWT: pip install 'oxbrook[auth]'.

With uv, a free-threaded environment is one command:

uv venv --python 3.14t
uv pip install oxbrook

Check which build is running with oxbrook --version.

Versions

Oxbrook is alpha. While the version is 0.x:

  • a patch release (0.1.1) fixes bugs and never changes the API;
  • a minor release (0.2.0) may change the API, and lists every change that breaks existing code under Breaking in the changelog.

Pin a minor version, oxbrook~=0.2.0, to take fixes without changes. 1.0 will mean the API is committed to.

From source

Building from the repository needs a Rust toolchain, uv, and Docker if the suites should cover durable topics:

git clone https://github.com/ishangavidusha/oxbrook
cd oxbrook
make venvs     # .venv (free-threaded 3.14t) and .venv-gil (standard 3.14)
make build     # maturin develop --release into both
make run       # examples/hello.py

On Windows, where there is no make, the same three steps are:

uv venv --python 3.14t .venv
uv pip install --python .venv/Scripts/python.exe maturin
.venv/Scripts/maturin.exe develop --release

Rebuild after any change to src/; the make targets that need it already do. The contributing guide covers the test suites and conventions.

First app

from oxbrook import App, Request

app = App(title="Notes", version="1.0.0")

@app.get("/notes/{note_id}")
async def read_note(_: Request, note_id: int):
    """Read one note by its id."""
    return {"id": note_id, "title": "hello"}

if __name__ == "__main__":
    app.run(port=8000)
oxbrook run app:app --reload     # or: python app.py

Installing Oxbrook puts two commands on the environment's path, oxbrook and its short form oxb. See Running a server for what they do.

That gives you, without further configuration:

  • GET /notes/1 returning JSON, and HEAD on the same path
  • 422 for GET /notes/abc, produced in Rust before Python is woken
  • 405 with an Allow header for DELETE /notes/1
  • GET /openapi.json and a documentation page at GET /docs
  • POST /mcp speaking the Model Context Protocol, exposing nothing until a route asks to be exposed

Services

Services run in containers rather than on the host.

make up      # start redis and postgres
make down    # stop them and remove their volumes
make stack   # build the app image and run two nodes against one redis

Handler rules

Handlers are async def, or a plain def on a route declared blocking=True. An undeclared synchronous handler is a TypeError at registration rather than a surprise at runtime, because a blocking call on a worker loop stalls every request that loop is carrying.

@app.get("/bad")
def wrong(_: Request):                  # TypeError, and it names the fix
    return {}

@app.get("/report", blocking=True)      # a `def` handler, off the loop
def report(_: Request):
    return slow_synchronous_query()