Hornbeam

Hornbeam is an Erlang-based WSGI/ASGI server that combines Python's web and ML capabilities with Erlang's strengths:

• Python handles: Web apps (WSGI/ASGI), ML models, data processing
• Erlang handles: Scaling (millions of connections), concurrency (no GIL), distribution (cluster RPC), fault tolerance, shared state (ETS)

The name combines "horn" (unicorn, like gunicorn) with "BEAM" (Erlang VM).

Features

• WSGI Support: Run standard WSGI Python applications
• ASGI Support: Run async ASGI Python applications (FastAPI, Starlette, etc.)
• WebSocket: Full WebSocket support for real-time apps
• HTTP via livery: HTTP/1.1 today; HTTP/2 and HTTP/3 listeners land with upcoming livery releases
• Shared State: ETS-backed state accessible from Python (concurrent-safe)
• Distributed RPC: Call functions on remote Erlang nodes
• Pub/Sub: pg-based publish/subscribe messaging
• ML Integration: Cache ML inference results in ETS
• Lifespan: ASGI lifespan protocol for app startup/shutdown
• Hot Reload: Leverage Erlang's hot code reloading

Quick Start

%% Start with a WSGI application
hornbeam:start("myapp:application").

%% Start ASGI app (FastAPI, Starlette, etc.)
hornbeam:start("main:app", #{worker_class => asgi}).

%% With all options
hornbeam:start("myapp:application", #{
    bind => <<"0.0.0.0:8642">>,
    num_contexts => 4,
    worker_class => asgi,
    lifespan => auto
}).

Installation

Add hornbeam to your rebar.config:

{deps, [
    {hornbeam, {git, "https://github.com/benoitc/hornbeam.git", {branch, "main"}}}
]}.

Python Integration

Shared State (ETS)

Python apps can use Erlang ETS for high-concurrency shared state:

from hornbeam_erlang import state_get, state_set, state_incr

def application(environ, start_response):
    # Atomic counter (millions of concurrent increments)
    views = state_incr(f'views:{path}')

    # Get/set cached data
    data = state_get('my_key')
    if data is None:
        data = compute_expensive()
        state_set('my_key', data)

    start_response('200 OK', [('Content-Type', 'text/plain')])
    return [f'Views: {views}'.encode()]

Distributed RPC

Call functions on remote Erlang nodes:

from hornbeam_erlang import rpc_call, nodes

def application(environ, start_response):
    # Get connected nodes
    connected = nodes()

    # Call ML model on GPU node
    result = rpc_call(
        'gpu@ml-server',      # Remote node
        'ml_model',           # Module
        'predict',            # Function
        [data],               # Args
        timeout_ms=30000
    )

    start_response('200 OK', [('Content-Type', 'application/json')])
    return [json.dumps(result).encode()]

ML Caching

Use ETS to cache ML inference results:

from hornbeam_ml import cached_inference, cache_stats

def application(environ, start_response):
    # Automatically cached by input hash
    embedding = cached_inference(model.encode, text)

    # Check cache stats
    stats = cache_stats()  # {'hits': 100, 'misses': 10, 'hit_rate': 0.91}

    start_response('200 OK', [('Content-Type', 'application/json')])
    return [json.dumps({'embedding': embedding}).encode()]

Pub/Sub Messaging

from hornbeam_erlang import publish

def application(environ, start_response):
    # Publish to topic (all subscribers notified)
    count = publish('updates', {'type': 'new_item', 'id': 123})

    start_response('200 OK', [('Content-Type', 'application/json')])
    return [json.dumps({'subscribers_notified': count}).encode()]

Examples

Hello World (WSGI)

# examples/hello_wsgi/app.py
def application(environ, start_response):
    start_response('200 OK', [('Content-Type', 'text/plain')])
    return [b'Hello from Hornbeam!']

hornbeam:start("app:application", #{pythonpath => ["examples/hello_wsgi"]}).

Hello World (ASGI)

# examples/hello_asgi/app.py
async def application(scope, receive, send):
    await send({
        'type': 'http.response.start',
        'status': 200,
        'headers': [[b'content-type', b'text/plain']],
    })
    await send({
        'type': 'http.response.body',
        'body': b'Hello from Hornbeam ASGI!',
    })

hornbeam:start("app:application", #{
    worker_class => asgi,
    pythonpath => ["examples/hello_asgi"]
}).

WebSocket Chat

# examples/websocket_chat/app.py
async def app(scope, receive, send):
    if scope['type'] == 'websocket':
        await send({'type': 'websocket.accept'})

        while True:
            message = await receive()
            if message['type'] == 'websocket.disconnect':
                break
            if message['type'] == 'websocket.receive':
                # Echo back
                await send({
                    'type': 'websocket.send',
                    'text': message.get('text', '')
                })

hornbeam:start("app:app", #{
    worker_class => asgi,
    pythonpath => ["examples/websocket_chat"]
}).

Embedding Service with ETS Caching

See examples/embedding_service/ for a complete ML embedding service using Erlang ETS for caching.

Distributed ML Inference

See examples/distributed_rpc/ for distributing ML inference across a cluster.

Running with Gunicorn (for comparison)

All examples are designed to work with gunicorn too (with fallback functions):

# With gunicorn (single process, no Erlang features)
cd examples/hello_wsgi
gunicorn app:application

# With hornbeam (Erlang concurrency, shared state, distribution)
rebar3 shell
> hornbeam:start("app:application", #{pythonpath => ["examples/hello_wsgi"]}).

Configuration

Via hornbeam:start/2

hornbeam:start("myapp:application", #{
    %% Server
    bind => <<"0.0.0.0:8642">>,
    ssl => false,
    certfile => undefined,
    keyfile => undefined,

    %% Protocol
    worker_class => wsgi,  % wsgi | asgi
    %% 'HTTP/2' and 'HTTP/3' require ssl => true
    http_version => ['HTTP/1.1'],

    %% Python contexts
    num_contexts => 4,      % defaults to the scheduler count
    num_acceptors => 100,
    max_concurrent => 10000,
    timeout => 30000,
    keepalive => 2,

    %% ASGI
    lifespan => auto,  % auto | on | off

    %% WebSocket
    websocket_timeout => 60000,
    websocket_max_frame_size => 16777216,  % 16MB

    %% Python
    pythonpath => [<<".">>]
}).

Via sys.config

%% Every option defaults in hornbeam_config:defaults/0; set a key here
%% only to override one.
[
    {hornbeam, [
        {bind, <<"127.0.0.1:8642">>},
        {worker_class, wsgi},
        {timeout, 30000},
        {pythonpath, [<<".">>]}
    ]}
].

API Reference

hornbeam module

Python hornbeam_erlang module

Python hornbeam_ml module

Performance

Hornbeam achieves high throughput by leveraging Erlang's lightweight process model and avoiding Python's GIL limitations.

Benchmark Results

Tested on Apple M4 Pro, Python 3.13, OTP 28 (February 2026):

Both servers configured with 4 workers, gunicorn with gthread and 4 threads per worker. Zero failed requests on both.

Latency Comparison

Run Your Own Benchmarks

# Quick benchmark
./benchmarks/quick_bench.sh

# Full benchmark suite
python benchmarks/run_benchmark.py

# Compare with gunicorn
python benchmarks/compare_servers.py

See the Benchmarking Guide for details.

Development

# Compile
rebar3 compile

# Run tests
rebar3 ct

# Start shell
rebar3 shell

License

Apache License 2.0