openhost-frontend-preview
Skill246 starsChanged 5 months agoMITView on GitHub
Live, hot-reloading preview of the Sculptor WEB frontend from a phone or any browser, served through the OpenHost nginx /proxy front. ONLY relevant when running INSIDE the openhost-deployed Sculptor (the container fronted by nginx on :5050, reachable at https://sculptor.<zone>/) — NOT for local or Electron dev. Frontend-only: it reuses the single shared backend, so it previews UI/frontend changes, not a per-workspace backend. Invoke when iterating on the web UI and wanting to see it live in a browser through the OpenHost SSO front.
In this repository23 other files it gives its agents.
- openhost-agent/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- address-commentsSkill
- auto-qa-changesSkill
- auto-qa-iphoneSkill
- batch-claude-runnerSkill
- code-review-checklistSkill
- cut-releaseSkill
- debug-integration-testSkill
- frontend-design-tokensSkill
- manually-qa-branchSkill
- measure-react-rendersSkill
- openhost-sculptorSkill
- post-pr-to-slackSkill
- profile-sculptor-backendSkill
- promote-releaseSkill
- run-integration-testSkill
- storybook-screenshotSkill
- update-help-docsSkill
- update-review-rulesSkill
- update-specsSkill
- write-integration-testSkill
- write-release-notesSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 16
Run a Vite dev server (HMR) for the Sculptor web UI and reach it from any logged-in browser — including a phone — through the OpenHost …
- Very specific: line 22
Use this ONLY inside the openhost-deployed Sculptor.
- Very specific: line 26
If those are NOT true (local dev, Electron, a plain backend on :5050), this skill does not apply — use normal pnpm run dev / just frontend …
- Very specific: line 70
Use a port in the 51000-51099 band.
- Very specific: line 111
Do NOT pkill -f vite... — the pattern matches your own shell command and kills the call.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
OpenHost frontend live preview (/proxy/<port>/)
Run a Vite dev server (HMR) for the Sculptor web UI and reach it from any logged-in browser — including a phone — through the OpenHost nginx front, entirely behind OpenHost's owner SSO. Nothing is exposed publicly.
When this applies — OpenHost only
Use this ONLY inside the openhost-deployed Sculptor. Quick checks:
test -f /app/openhost-nginx.conf(the nginx front config), and- PID 1 is nginx:
ps -p 1 -o args=->nginx ...(backend is on loopback :5051).
If those are NOT true (local dev, Electron, a plain backend on :5050), this skill
does not apply — use normal pnpm run dev / just frontend there instead.
How it works (read first)
- nginx owns :5050 (the only port OpenHost proxies) and routes
/proxy/<port>/*->127.0.0.1:<port>; everything else -> the backend on :5051. - A preview is just a Vite dev server on a loopback port in the 51000-59999
band, served with
base=/proxy/<port>/, dialing HMR back overwss://...:443/proxy/<port>/. Its/api+/wscalls are same-origin absolute, so they hit the ONE shared backend — there is no per-preview backend. - So this previews frontend changes. Full-stack per-workspace instances (each with its own backend) are not supported on one origin: every backend would set the same session cookie on the same origin, and they collide.
What surrounds a preview (already wired — don't rebuild it)
- Switchboard + down-page:
/proxy/(no port) serves a self-contained page (openhost-preview-fallback.html, repo root) that scans the band from the browser and links to live previews. nginx serves the SAME page when a/proxy/<port>/target is dead, with a way back and an auto-reload poll that returns to the preview once its server is back. - Identity meta: each preview's index.html carries
<meta name="sculptor-preview" content="<branch>@<sha>[*]">(*= dirty tree), injected per request bypreviewIdentityinsculptor/frontend/vite.base.config.tsunderSCULPTOR_OPENHOST_PROXY. A tree with no.gitreports the frontend dir it serves from instead — e.g./app/sculptor/frontendfor a preview of the deploy image, which ships no git history. The switchboard and the switcher extension show this label. - Preview-switcher pill: the
openhost-preview-switcherextension (sculptor/frontend/extensions/, auto-installed at boot byopenhost-run.sh) renders a bottom-left pill in the deployed app listing live previews in 51000-51099, and an amber badge with a way back when ON a preview. Switching preserves the#/route. - HMR keepalive: the dev server sends a no-op custom HMR event to every
client every 25s (
previewHmrKeepaliveinsculptor/frontend/vite.base.config.ts, alsoSCULPTOR_OPENHOST_PROXY-gated). Without it the idle HMR websocket gets killed by the edge and Vite hard-reloads the page about once a minute (and on every return from the background). If "random reloads" ever reappear, check the keepalive before suspecting app code.
Run a preview
Use a port in the 51000-51099 band. The preview-switcher pill in the
deployed app only auto-discovers that range (and the /proxy/ switchboard page,
openhost-preview-fallback.html, quick-scans it on load), so a preview there shows
up without a full-band scan. A higher port (51100-59999) still works, but it will
not appear in the pill — you'd reach it only via the switchboard's full-band
scan or a direct /proxy/<port>/ URL, so don't reach for a random high port. The
zero-friction way to get a valid one is to let the script pick: run
launch-preview.sh with no argument and it auto-selects a free 51000-51099
port (printed to the log).
Launch it DETACHED — do NOT use a tracked background task; this Sculptor will not release your turn to the user while one is alive:
cd <frontend-dir>
setsid bash launch-preview.sh 51042 >/tmp/vite-51042.log 2>&1 </dev/null &(or setsid bash launch-preview.sh >/tmp/vite-preview.log 2>&1 </dev/null & with
no port to auto-pick a free 510xx one — then read the chosen port and the
ready in line from the log.)
<frontend-dir> is either:
/app/sculptor/frontend— preview the deployed UI as-is (itsnode_modulesand.venvare already there, so it starts fast), or- your workspace's
sculptor/frontend— preview YOUR edits with HMR. A fresh worktree has nonode_modules, so runpnpm installthere once first (slow), then launch.
launch-preview.sh [port] sets SCULPTOR_FRONTEND_PORT + SCULPTOR_OPENHOST_PROXY
and runs pnpm run dev — the /proxy/<port>/ base AND the OpenHost wss/HMR
override are both derived from those env vars in vite.base.config.ts, so do NOT
pass --base yourself (pnpm forwards a stray -- that Vite reads as
end-of-options and silently drops the flag). First start pre-bundles deps
(~tens of seconds) — watch
/tmp/vite-<port>.log for ready in. Then open, on any logged-in browser:
https://sculptor.<your-zone>/proxy/51042/Edits to the frontend source hot-reload live.
Stop a preview
Do NOT pkill -f vite... — the pattern matches your own shell command and kills
the call. Stop by port -> pid -> process group:
PID=$(ss -tlnpH | grep ':51042' | grep -oE 'pid=[0-9]+' | head -1 | cut -d= -f2)
PGID=$(ps -o pgid= -p "$PID" | tr -d ' ')
kill -9 -"$PGID"Gotchas
- Detached, not background. Launch via
setsid ... &from a normal foreground command so your turn releases. Arun_in_backgroundtask or persistentMonitorblocks the user from talking to you until it ends. - One browser per workspace page. Sculptor syncs tab state via
localStorage, so the same workspace open in two browsers can desync — preview on a different page/tab than the one you're chatting in. - Same-origin trust. Previews share the app's origin, so preview JS runs with your session's privileges — only run frontend code you trust.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

