Host an add-on

An add-on is a public HTTP endpoint. There is no special hosting requirement: any platform that can serve a JSON response from a Node, Python, Go, Rust, or PHP runtime will do. This page covers the constraints wako enforces, the deployment patterns that work well in practice, and the gotchas that catch first-time add-on authors.

Requirements

• HTTPS in production. Some user networks (corporate, cellular carriers, public Wi-Fi) silently rewrite plain HTTP, which breaks add-on calls in unpredictable ways. Modern hosts ship HTTPS for free — there is no reason to deploy with plain HTTP.
• CORS open for all origins. Add Access-Control-Allow-Origin: * on every response. wako fetches from a native context where CORS is not strictly enforced, but every browser-based debug tool relies on it.
• Stable URL. Users paste your manifest URL once and forget about it. wako re-fetches the manifest periodically, so the URL must keep working. Avoid hosting on URLs that include a build hash or expire after inactivity.
• Reasonable latency. wako times stream calls out at 40 seconds, meta and catalog at 10 seconds, subtitles at 3.5 seconds. Aim for an order of magnitude below those limits.

CORS headers

The minimum a wako add-on should set on every response:

Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: GET, HEAD, OPTIONS

Always respond to OPTIONS preflights with a 200 and the same headers — most browser debug tools will issue one before the actual request.

Deployment targets

Most add-on authors do not run a server full-time. These platforms all ship HTTPS, ship-fast deployments, and a generous free tier:

Serverless functions

• Cloudflare Workers. Cold-start under 5 ms, free tier of 100 000 requests/day. Ideal for add-ons that return static or lightly-computed responses.
• Vercel. Easy Git-driven deploys, good for Node and Python. Manifest URLs end up at https://my-addon.vercel.app/manifest.json.
• Deno Deploy. Native TypeScript runtime, free tier enough for small audiences.
• Netlify Functions. Same shape as Vercel; works with any static-site generator if you also ship a configuration page.

Long-running servers

• Fly.io / Railway / Render. Run a Node/Go/Python server with a stable URL. Better when your add-on needs persistent connections (database, background scrape).
• Your own VPS. A 5€/month VPS with caddy or nginx for TLS, behind a domain name, is the most boring and reliable option.

Local development

Run your add-on on 127.0.0.1 and install it in wako from a phone or TV on the same network using your laptop's LAN IP. wako accepts http:// URLs for testing — keep https:// for production.

http://192.168.1.42:7000/manifest.json

For Android TV, your laptop and the TV must be on the same Wi-Fi network. If they are not, use a tunnel (Cloudflare Tunnel, Tailscale, ngrok) to expose your local server to a public URL.

Configuration flow

Add-ons that require user input (API keys, content filters, preferred languages) typically follow this pattern:

1. Ship a configuration page at https://my-addon.example/configure. Users open it in a browser and fill a form.
2. Encode the configuration into a URL segment when the user submits (https://my-addon.example/CONFIG_STRING/manifest.json).
3. Provide a copy button or deep-link so the user can paste the configured manifest URL into wako.

Inside the add-on, parse the URL segment to extract the configuration and apply it to every subsequent request. This keeps your add-on stateless and lets the same instance serve many users with different configurations.

Declare the configuration capability in the manifest:

{
  "behaviorHints": {
    "configurable": true
  }
}

wako displays a configuration button in the add-on detail page when this flag is true. The button opens https://my-addon.example/configure in the device browser — wako derives it by replacing /manifest.json at the end of the installed URL with /configure.

Versioning and updates

Bump manifest.version when the contract changes. Adding a catalog, changing a resource declaration, or fixing a wrong type — all warrant a new version. wako auto-detects manifest changes within 24 hours and refreshes the stored copy, so users do not need to reinstall.

For non-breaking content changes (a new entry in an existing catalog, a better stream), no version bump is needed — your data lives on the endpoints, not in the manifest.

Best practices

• Cache aggressively. wako issues bursts of requests when a user lands on the home screen. Even a 30-second in-memory cache for catalog responses drops 95 % of repeat load.
• Be honest with errors. Returning { "streams": [] } with HTTP 200 is the right shape for "no result". Reserve non-200 status codes for actual failures so wako can surface them to the user.
• Compress responses. wako does not require compression, but enabling gzip/brotli on your host shaves hundreds of milliseconds off large catalog responses on slow networks.
• Use IMDb IDs. They make your content discoverable across every other add-on — streams, subtitles, watchlist sync. See the Catalog page.