On this page

Self-hosting

Omnillink is free software under the MIT licence. You need Node.js 22 or newer; Redis is optional.

With Node.js

Terminal
git clone https://github.com/kayzen-lyon/linkforge.git
cd linkforge
npm install
npx playwright-core install chromium
cp .env.example .env
npm run dev

The API listens on http://localhost:3000. npm run build then npm start run the compiled version.

On Vercel

The repository contains the configuration of a single serverless function deployment that serves both the API and this site. The root directory of the Vercel project is apps/api.

  • On Vercel, Chromium comes from the @sparticuz/chromium package, which is made for serverless functions.
  • Without Redis the cache lives in memory, per instance. Add REDIS_URL to share it.
  • The first render of a cold instance is slower: Chromium has to start first.

Environment variables

All of them are optional. The defaults suit a local trial.

VariableDefaultPurpose
PORT, HOSTDefault3000, 0.0.0.0PurposeListening address.
REDIS_URLDefaultemptyPurposeShared cache. Empty: in-memory cache.
API_KEYSDefaultemptyPurposeKeys accepted in x-api-key, comma-separated, 16 to 256 characters.
RATE_LIMIT_MAXDefault60PurposeRequests per window and per IP address.
RATE_LIMIT_KEY_MAXDefault600PurposeRequests per window and per key.
RATE_LIMIT_WINDOW_MSDefault60000PurposeLength of the window.
CACHE_*_TTL_SECONDSDefault3600PurposeCache lifetime per endpoint: META, SCREENSHOT, PDF, EXTRACT, CONTENT.
HTTP_TIMEOUT_MSDefault10000PurposeTimeout of the HTTP read.
BROWSER_NAVIGATION_TIMEOUT_MSDefault20000PurposeNavigation timeout in Chromium.
BROWSER_MAX_CONCURRENCYDefault4PurposePages rendered in parallel (2 on serverless).
REQUEST_DEADLINE_MSDefault55000PurposeOverall deadline of a request.
SSRF_ALLOWED_PORTSDefault80,443PurposeAllowed destination ports.
SSRF_BLOCKED_HOSTSDefaultemptyPurposeExtra refused destinations, host or host:port. This list can only restrict.
BROWSER_PAGE_MAX_REQUESTSDefault1500PurposeRequests at most per rendered page.
BROWSER_PAGE_MAX_BYTESDefault60 MB (30 on serverless)PurposeBytes received at most per rendered page.
CIRCUIT_BREAKER_THRESHOLDDefault5PurposeConsecutive network failures before a host is set aside.
CIRCUIT_BREAKER_COOLDOWN_MSDefault30000PurposeHow long it is set aside.
ANIMATION_MAX_BYTESDefault10 MB (4 on serverless)PurposeMaximum size of an animated capture.
METRICS_TOKENDefaultemptyPurposeToken that protects /metrics (Prometheus format). Empty: the route does not exist.
MCP_ENABLEDDefaulttruePurposeTurns on the MCP endpoint POST /mcp.
CORS_ORIGINDefault*PurposeOrigins allowed to call the API from a browser.

SSRF_ALLOW_PRIVATE_NETWORKS=true allows local and private addresses. It exists for tests: the API refuses to start with it when NODE_ENV=production.

Checking the installation

Terminal
curl http://localhost:3000/health

The answer gives the uptime, the cache backend and the state of the browser pool. The Status page shows the same for this instance.

Keyboard shortcuts

CtrlKor/
Open search and commands
?
Show this help
←→
Move from one tab to the next
Ctrl↵
Run the request in the playground
Esc
Close a panel or a menu

Single-key shortcuts can be turned off in the accessibility options.