| name | openhost-environment |
| description | How this OpenHost-hosted Sculptor environment works — storage and what survives
restarts, where/how to add repositories and authorize gh, and the /proxy/<port>/
capability for previewing loopback web apps from a browser. ONLY relevant when
running inside an OpenHost deployment (detect via the OPENHOST_* env vars, e.g.
OPENHOST_APP_NAME). Ships with the deploy image and is refreshed every release.
|
Running inside an OpenHost-hosted Sculptor
You're in a Sculptor instance deployed as an OpenHost app if the OPENHOST_*
env vars are set (OPENHOST_APP_NAME, OPENHOST_APP_DATA_DIR,
OPENHOST_ZONE_DOMAIN, …). The public URL is
https://$OPENHOST_APP_NAME.$OPENHOST_ZONE_DOMAIN/, behind OpenHost's owner SSO.
If those vars are absent, this skill does not apply.
Storage — what survives a restart/rebuild
- Only
$OPENHOST_APP_DATA_DIR (/data/app_data/<app>) persists across
reloads/rebuilds — it's the backed-up app-data mount. The DB, workspaces, Claude
config/creds, and the gh token all live under it.
/home is wiped on every rebuild — clones, ~/.gitconfig (git identity +
the gh auth setup-git credential wiring), and scratch are all lost.- So keep anything durable under the app-data dir, never in
/home.
Adding repositories + gh auth
- Add repos via the app (Settings → Repositories) or
sculpt
(sculpt workspace list --repo <path> registers one). Clone to a persisted
path, not /home.
- gh auth:
gh auth login (device flow — paste the one-time code in a
browser). The token persists (the gh config dir is under the app-data mount),
but the git credential-helper wiring + identity live in ~/.gitconfig and reset
on rebuild. The deploy's run script re-runs gh auth setup-git and sets a
gh-derived identity on boot (best-effort); if a push ever fails to auth after a
rebuild, re-run gh auth setup-git and set git config --global user.{name,email}.
/proxy/<port>/ — preview a loopback web app from any browser
OpenHost publicly proxies only port 5050 (behind owner SSO); an in-container
nginx fronts it and adds a reverse proxy:
https://$OPENHOST_APP_NAME.$OPENHOST_ZONE_DOMAIN/proxy/<port>/ forwards to
127.0.0.1:<port> for any port in 51000–59999, all behind SSO. Nothing is
made public.- Use it to preview any simple loopback web app or dev server (not just Vite),
including from a phone. The URI is passed through unstripped, so the app must
be base-aware — served under
/proxy/<port>/ (e.g. a dev server's base/prefix
option), since fully transparent rewriting of an app's absolute URLs isn't done.
- Caveat — shared origin: the preview shares the root app's origin, so its
cookies/paths must not collide with Sculptor's (the session cookie in
particular). Simple apps with their own non-overlapping cookies/paths are fine; a
second full Sculptor backend is not (its session cookie would collide).
/proxy/ (no port) is a switchboard: a small nginx-served page that scans
the band from the browser and links to the live previews it finds. The same
page is served when a /proxy/<port>/ target is dead ("preview is not
running", with a way back and an auto-reload once the server returns), so a
phone PWA — which has no URL bar — can never get stranded on a dead preview.- The deployed Sculptor UI also shows a preview-switcher pill (bottom-left
footer corner): the
openhost-preview-switcher extension, auto-installed
at boot from the image, lists live previews and switches between them and the
deployed app in place.
- For the Sculptor web frontend specifically, use the
openhost-frontend-preview
skill / sculptor/frontend/launch-preview.sh (when working in the sculptor repo).
Turn-handling (matters here)
This Sculptor does not release your turn to the user while a tracked
run_in_background Bash task or a persistent Monitor is alive. Launch long-lived
servers detached from a normal foreground command instead:
setsid <cmd> >/tmp/x.log 2>&1 </dev/null &. Detached/orphaned processes keep
running and don't hold the turn; check on them later via ps / curl / log reads.
This skill ships with the OpenHost deploy image and is refreshed on every release,
so it stays current. The owner's standing instructions live in the seeded
AGENTS.md in the same config dir.
