Skip to content

Installation

Requirements

Python 3.12, 3.13 or 3.14. Free-threaded 3.14 (3.14t) is the fast path — see below.
OS Linux (x86_64/aarch64), macOS (Apple Silicon/Intel), Windows (x64)
Rust Only if building from source, or installing from an sdist

From PyPI

$ pip install web-cortex-framework

On CPython 3.14, use 0.3.2 or later

0.3.1 and earlier fail to import on CPython 3.14.7 with ValueError: module functions cannot set METH_CLASS or METH_STATIC. This was a pyo3 bug, fixed in 0.3.2. Nothing to work around — just upgrade.

The distribution is web-cortex-framework; the import is webcortex. Same split as djangorestframework → import rest_framework.

from webcortex import WebCortex   # not "web_cortex_framework"

From source

$ git clone https://github.com/slimboi34/web_cortex_framework
$ cd web_cortex_framework
$ uv venv --python 3.14t         # or 3.12 / 3.13 / 3.14
$ uv pip install maturin
$ .venv/bin/maturin develop --uv

maturin develop compiles the Rust extension and installs the package as editable. First build takes a few minutes; later ones are incremental.

Verify:

$ .venv/bin/webcortex --help
$ .venv/bin/python -c "import webcortex; print(webcortex.__version__)"
2.9.1

Free-threaded Python

This is the difference between WebCortex being fast and being very fast for Python-backed routes.

$ uv venv --python 3.14t          # the 't' suffix means free-threaded
$ pyenv install 3.14.7t
$ pyenv local 3.14.7t

Choose the "free-threaded" variant during installation, then use python3.14t.

Check which you are on:

import webcortex
print(webcortex.free_threaded())   # True on a GIL-disabled build

webcortex dev prints it at startup:

  python 3.14.7 (free-threaded)

Why it matters

On a GIL build, N Python worker threads give concurrency for I/O and nothing for CPU. On a free-threaded build they give real parallelism.

Measured on identical hardware with the same client driving both servers:

Concurrency free-threaded GIL
1 1.00x 1.00x
2 2.23x 1.45x
4 3.55x 1.42x
8 4.82x 1.38x

It works either way

WebCortex runs correctly on a GIL build. It checks sys._is_gil_enabled(), sizes its worker pools accordingly, and tells you which mode it is in. Free-threading is the fast path, not a hard requirement — so adoption is never blocked on a dependency that has not caught up.

The catch

C extensions without free-threading support will either fail to import or silently re-enable the GIL. Pure-Python and Rust-backed packages are fine; the long tail of older C extensions is not. If a dependency forces the GIL back on, WebCortex keeps working — it just reports free_threaded() == False.

Your first project

$ webcortex new myapp --template api
$ cd myapp
$ export WEBCORTEX_API_KEY=$(webcortex keygen)
$ webcortex dev

Seven starters are available (webcortex new myapp --template <name>):

Template What you get
api JSON API + MCP tool surface
fullstack The above, plus server-rendered pages and static assets
agent The above, plus an agent with an approval-gated tool
behaviour The above, plus Behaviours — programmable procedures
orchestration Handoffs, flows, memory, context providers and a local-model tier
robotics A camera agents can see through, gated actuators and an emergency stop, booting halted (Vision and robotics)
hub Cameras and sensors streaming to agents, with insights to subscribers and webhooks (The device hub)

Every starter boots with authentication, rate limiting, and security headers already enabled. A starter that generates an insecure app teaches an insecure habit. For the same reason the .env.example a starter writes leaves its keys empty: run webcortex keygen for each. A key that is empty or still starts with replace-me is never accepted, and webcortex doctor fails on it.

Tutorial