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 answerOPTIONSwith204. 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:
cd services/template # or your copy of it
npx wrangler login
npx wrangler deploy # prints https://<name>.<your-subdomain>.workers.devAdd /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:
# 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"]# 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"]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:
# 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:
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:
manifest.json
catalog/audiobook/christmas.json
catalog/audiobook/autumn.json/*
Access-Control-Allow-Origin: *
Cache-Control: public, max-age=3600Declare 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:
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
404for an unknown ID included, hasaccess-control-allow-origin: *and a JSON body. - The
OPTIONSrequest answers204. - The manifest passes the manifest checker.
Then open Settings → Add-ons in Lelap, paste the manifest URL and add it.