HTMLinks

Self-host HTMLinks with Docker

Run HTMLinks with Docker Compose and PostgreSQL, configure your canonical HTTPS origin, connect the agent skill, and back up your documents.

By Michael Elkabetz · HTMLinks maintainer

Start a local instance

HTMLinks is MIT-licensed and can run on your infrastructure. Docker Compose provides PostgreSQL, migrations, private upload storage, the web service, and maintenance. Install Docker Compose and Node.js 22.22+ before initialization.

git clone https://github.com/michael-elkabetz/HTMLinks.git
cd HTMLinks
node scripts/init.mjs
docker compose up --build -d

Open http://localhost:3000. The site, API, and shared pages under /rendered/ use the same origin. Uploaded HTML executes in an opaque sandbox. There is no registration or owner setup step.

Connect your agent to this instance

Install the Agent Skill, then choose self-hosted on first use and supply your server origin. You can also use the helper in this checkout:

node skills/htmlinks/scripts/htmlinks.mjs config --hosting self-hosted --url http://localhost:3000
node skills/htmlinks/scripts/htmlinks.mjs upload examples/idea.html

Recipients need access to that server to open shared links. A localhost link only works on the machine running the instance; configure a reachable HTTPS domain for remote recipients.

Configure public hosting and backups

Set APP_URL to your canonical HTTPS origin before starting production. The proxy validates that host, and generated links and canonical metadata use it. Configure your reverse proxy to preserve the intended host. Review upload/storage limits and enable TRUST_PROXY only behind ingress that replaces forwarded client headers.

Public marketing-page indexing defaults to the managed HTMLinks domain. For an intentionally public self-hosted site, set INDEX_PUBLIC_SITE=1. Set it to 0 on staging/private deployments. This controls discovery signals, not access permissions; customer documents remain noindexed in either mode.

Back up PostgreSQL, uploaded files, HTMLINKS_SECRET, and each author’s local management-key directory. Compose named volumes retain data when services stop; removing the volumes deletes it. Self-hosting has infrastructure costs even though the source license is free.

For Supabase storage, use the Supabase configuration. See the repository’s deployment guide for operations and Render instructions for that platform.

Install the skill