ogthing – inspect link metadata from your own machine

ogthing is golbat energy for your localhost: a metadata inspector that runs on your device so the urls you actually care about — localhost:3000, your dev preview, your coworker's half-finished branch deployed on port 8080 — can be inspected directly. no tunnel, no deploy, no public exposure.

usage

on your machine:

bunx ogthing

your browser opens the inspector. paste any url, including local ones:

http://localhost:3000        # works. it is running next to you.

the exact url is printed in the terminal. if a compatible Portless proxy is already running, ogthing reuses it and normally opens:

https://ogthing.localhost

otherwise it starts its own unprivileged HTTP proxy, usually at:

http://ogthing.localhost:1355

no sudo prompt is needed just to get a nice name for localhost.

if you want the clean HTTPS url, start Portless yourself before running ogthing:

portless proxy start --https --tld localhost
bunx ogthing

what it does

• fetches the page from your machine, then parses title, description, Open Graph, Twitter/X card, favicon, canonical, robots and viewport tags
• previews how the link renders on Telegram, Discord, Slack, X, Facebook, LinkedIn, and WhatsApp
• scores metadata quality out of 100 with per-check pass/fail dots
• picks the user agent the way real crawlers do: facebookbot, twitterbot, slackbot, discordbot, telegrambot, WhatsApp, LinkedInBot, or a plain browser (some sites only serve their social tags to known bots)
• validates image dimensions against recommended sizes (1200×630 for OG)
• checks for robots.txt and sitemap.xml
• copies the metadata as JSON or as ready-to-paste HTML meta tags
• keeps your last few inspected urls around

keyboard shortcuts: keys 1-7 switch tabs while results are showing.

because the fetch happens on your device rather than on some hosted inspector, sites behind your firewall, your docker network, and plain old localhost are all fair game. that is the whole point.

requirements

• Bun 1.3.14 or newer

Portless ships with ogthing. you do not need to install it separately.

environment variables

the useful ones:

• OGTHING_PORT – local app/API port (default: 4646)
• OGTHING_NO_OPEN=1 – start without opening a browser
• OGTHING_FETCH_TIMEOUT_MS – fetch timeout in ms (default: 15000)

Portless knobs, if you need them:

• OGTHING_PROXY_PORT – preferred proxy port (default: 443)
• OGTHING_PROXY_TLS=0 – use HTTP for the preferred proxy
• OGTHING_FALLBACK_PROXY_PORT – unprivileged fallback port (default: 1355)
• OGTHING_FALLBACK_PROXY_TLS=1 – use HTTPS on the fallback port
• OGTHING_PORTLESS_STATE_DIR – state for the proxy ogthing starts (default: ~/.ogthing/portless)
• OGTHING_NO_PORTLESS=1 – serve directly on 127.0.0.1:<port> instead
• OGTHING_NO_PORTLESS_AUTOSTART=1 – fail instead of starting a proxy automatically

example:

OGTHING_NO_OPEN=1 OGTHING_PORT=5000 bunx ogthing

trust and privacy

ogthing does not send your urls anywhere except to the sites themselves. every request goes straight from your machine to the target host.

note that the inspector will happily fetch internal addresses — that feature is not a bug. do not expose your ogthing port or its Portless route to networks you do not trust; it has no authentication and it makes requests on behalf of whoever asks.

troubleshooting

• the browser opened the wrong url – use the exact url printed by ogthing. a fresh setup normally uses http://ogthing.localhost:1355, not HTTPS on port 443.
• a site shows no og tags – try a crawler user agent in the selector; some sites gate social metadata on bot user agents.
• Safari cannot resolve ogthing.localhost – Chrome, Firefox, and Edge resolve .localhost natively. for Safari, run portless hosts sync once.

development

install dependencies and run the named local app:

bun install
bun run dev:named

run the checks:

bun run typecheck
bun run lint
bun run format:check
bun test
bun run build
bun run pack:check

for a direct smoke test without Portless or a browser:

OGTHING_NO_PORTLESS=1 OGTHING_NO_OPEN=1 bun bin/ogthing.mjs

the parser reads the html itself because asking permission from cheerio for seven tags felt excessive.