---
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.*