Hosting

An add-on is a few GET routes that answer JSON, so it runs anywhere that serves HTTP. It stores nothing and never carries audio, so a free plan or a small machine is plenty.

What every host needs

  • HTTPS. The web app runs on an HTTPS page and can’t reach plain HTTP. Share only HTTPS URLs; a LAN address is fine for trying the add-on on your own phone.
  • CORS for everyone. Send Access-Control-Allow-Origin: * on every response, errors included, and answer OPTIONS with 204. The web app calls add-ons straight from the listener’s browser; without the header it sees nothing.
  • Paths as they arrive. IDs in paths are percent-encoded (example%3Araven). Proxies and hosts in front of the add-on must pass them on unchanged.
  • JSON answers within 10 seconds, with Content-Type: application/json. The app gives up on slower add-ons.
  • A stable URL. Listeners keep the manifest URL; if it moves, they have to add the add-on again.

The SDK and the samples already do the first four. Audio URLs in your streams point at wherever the files are; the app fetches them from there, never through your add-on.

Cloudflare Workers

The template is a Worker. Workers come with HTTPS, a workers.dev address and a free plan that covers a busy add-on. Rename the worker in wrangler.toml, then:

Terminal
cd services/template     # or your copy of it
npx wrangler login
npx wrangler deploy      # prints https://<name>.<your-subdomain>.workers.dev

Add /manifest.json to the printed URL and paste that into Lelap. To use your own domain, add it to the worker under Settings → Domains & Routes in the Cloudflare dashboard. The seasonal catalogs sample deploys the same way. Lelap’s own add-ons run like this too.

Docker and Node hosts

Any machine or platform that runs a container or a Node process can host an add-on: a VPS, a home server, or a platform that builds from a Dockerfile. Listen on the port in PORT, since most platforms set it.

The SDK or Hono on Node

addon.fetch and a Hono app are standard fetch(request) handlers. Serve them with @hono/node-server:

// server.ts, for any Node host: npm install @hono/node-server
import { serve } from '@hono/node-server';

import app from './src/index';

serve({ fetch: app.fetch, port: Number(process.env.PORT ?? 8787) });

Or without a dependency, with a few lines of node:http. Lelap’s self-hosting images serve its services the same way.

// Serves any fetch(request) handler, such as addon.fetch, with node:http alone.
import { createServer } from 'node:http';

import { addon } from './src/addon';

createServer(async (req, res) => {
  const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
  const response = await addon.fetch(new Request(url, { method: req.method }));
  res.writeHead(response.status, Object.fromEntries(response.headers));
  res.end(Buffer.from(await response.arrayBuffer()));
}).listen(Number(process.env.PORT ?? 8787));

Containers

The plain Node and Python samples need nothing installed, so their images are short:

examples/node-addon/Dockerfile
# No dependencies, so no install step.
FROM node:24-alpine
WORKDIR /app
COPY addon.mjs server.mjs ./
USER node
ENV PORT=8787
EXPOSE 8787
CMD ["node", "server.mjs"]
examples/python-addon/Dockerfile
# The standard library only, so no install step.
FROM python:3.13-alpine
WORKDIR /app
COPY addon.py ./
USER nobody
ENV PORT=8787
EXPOSE 8787
CMD ["python3", "addon.py"]
compose.yml
services:
  addon:
    build: .
    restart: unless-stopped
    ports:
      - '127.0.0.1:8787:8787'

The port is bound to 127.0.0.1, so only the HTTPS proxy on the same machine reaches it.

HTTPS in front

On your own machine, put a reverse proxy with a certificate in front of the add-on. Caddy gets one from Let’s Encrypt by itself:

Caddyfile
# Caddy gets and renews the certificate on its own.
addon.example.com {
	reverse_proxy 127.0.0.1:8787
}

With nginx, leave the path off proxy_pass; with a path, nginx decodes %3A and %2F in IDs before passing them on:

nginx
location / {
    # No path after the port: nginx then passes the path on as it arrived, still encoded.
    proxy_pass http://127.0.0.1:8787;
}

Your proxy may add its own CORS headers; make sure it doesn’t remove the add-on’s or send a second Access-Control-Allow-Origin, which browsers reject.

Static files

An add-on with only fixed catalogs and no extras, like the seasonal catalogs, can be plain files on any static host that serves HTTPS and lets you send the CORS header:

Files
manifest.json
catalog/audiobook/christmas.json
catalog/audiobook/autumn.json
_headers (on hosts that read one)
/*
  Access-Control-Allow-Origin: *
  Cache-Control: public, max-age=3600

Declare only catalog in resources, with no extras. Search, genres, paging and percent-encoded IDs in meta and stream paths need a server.

Check it

From any terminal, before you share the URL:

Terminal
curl -i https://addon.example.com/manifest.json
curl -i https://addon.example.com/meta/audiobook/example%3Araven.json
curl -i -X OPTIONS https://addon.example.com/manifest.json
  • Every answer, the 404 for an unknown ID included, has access-control-allow-origin: * and a JSON body.
  • The OPTIONS request answers 204.
  • The manifest passes the manifest checker.

Then open Settings → Add-ons in Lelap, paste the manifest URL and add it.