codehost 0.1.0 → 0.3.1

package/.github/workflows/deploy.yml

@@ -0,0 +1,30 @@
+name: Deploy
+
+# Auto-build + deploy the Cloudflare Pages site and signaling Worker on push to
+# main (the "git integration / auto build" for codehost.dev). Needs repo
+# secrets CLOUDFLARE_API_TOKEN (Workers Scripts:Edit + Pages:Edit) and
+# CLOUDFLARE_ACCOUNT_ID.
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: deploy
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - run: bun run build
+      - name: Deploy Pages (app + service worker)
+        run: bunx wrangler pages deploy dist/public --project-name codehost --branch main --commit-dirty=true
+      - name: Deploy signaling Worker
+        run: bunx wrangler deploy
+        working-directory: worker

package/.github/workflows/release.yaml

@@ -0,0 +1,39 @@
+name: Release
+
+# Publishes to npm via semantic-release using npm trusted publishing (OIDC) —
+# no NPM_TOKEN. Requires: a trusted publisher configured on npm for this repo +
+# this workflow file (release.yaml), id-token: write, semantic-release v25 /
+# @semantic-release/npm v13, and npm >= 11.5.1.
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write # semantic-release commits the version bump + tag
+  issues: write
+  pull-requests: write
+  id-token: write # OIDC token for npm trusted publishing
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      # Provides node + npm; do NOT set registry-url (it writes an .npmrc that
+      # breaks semantic-release's auth). Upgrade npm for OIDC support.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: npm install -g npm@latest
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - run: bunx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.releaserc.json

@@ -0,0 +1,17 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["package.json", "CHANGELOG.md"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+## [0.3.1](https://github.com/snomiao/codehost/compare/v0.3.0...v0.3.1) (2026-06-07)
+
+
+### Bug Fixes
+
+* add repository metadata so npm provenance publish succeeds ([e794bc2](https://github.com/snomiao/codehost/commit/e794bc2cef66276a53ca9fca9bece1a056bef703))
+
+# [0.3.0](https://github.com/snomiao/codehost/compare/v0.2.0...v0.3.0) (2026-06-07)
+
+
+### Features
+
+* open token URL after setup/serve and auto-connect a single server ([b6183a2](https://github.com/snomiao/codehost/commit/b6183a2dc35e3e2ce1b4dffa8d4228fab377f4e3))
+
+# [0.2.0](https://github.com/snomiao/codehost/compare/v0.1.1...v0.2.0) (2026-06-05)
+
+
+### Bug Fixes
+
+* oxmgr works under bun/bunx and on Windows (no Node, no global install) ([b339b31](https://github.com/snomiao/codehost/commit/b339b319c7147eee4e99c5abe977ace3146e41d6))
+* tunnel VS Code's resource URLs via the real host, not 127.0.0.1 ([c9d22e2](https://github.com/snomiao/codehost/commit/c9d22e27946464252cd753424f0e267eb664fb93))
+
+
+### Features
+
+* `-d` enables login auto-start via oxmgr's service integration ([623e022](https://github.com/snomiao/codehost/commit/623e02291cf0d1bc4c71c0344b333e93e72783db))
+* `codehost expose <port>` — tunnel any local HTTP/WS server over WebRTC ([1ec57f4](https://github.com/snomiao/codehost/commit/1ec57f4f8d221b699c8f713b2eb6f0e2187665b7))
+* deep-link to a live workspace via codehost.dev/gh/<owner>/<repo>/tree/<branch> ([1567ba7](https://github.com/snomiao/codehost/commit/1567ba7e64b821d5dea989235db63c5f22d9b4c9))
+* proxy VS Code's CORS-less CDN through the signaling Worker ([0a362ee](https://github.com/snomiao/codehost/commit/0a362ee0d0c3247963da72bcc3b12365711c6d4a))

package/README.md

@@ -20,15 +20,32 @@ directly; a tiny Cloudflare Worker only brokers the handshake.
 
 ## Quickstart
 
-On the machine you want to edit (needs the `code` CLI and [Bun](https://bun.sh)):
+On the machine you want to edit, run the one-line installer — it installs
+[Bun](https://bun.sh) if needed, the `codehost` CLI, and then `codehost setup`
+(picks a token, installs VS Code, and starts a server):
 
 ```bash
-bunx codehost serve -d -t <token>
+# macOS / Linux
+curl -fsSL https://codehost.dev/install.sh | sh
+
+# Windows (PowerShell)
+powershell -c "irm codehost.dev/install.ps1 | iex"
 ```
 
-Then open **https://codehost.dev**, enter the same `<token>`, and your server
-appears in the list. Click **Connect** — VS Code loads in the page, served
-entirely over the peer-to-peer data channel.
+Already have Bun? `bun add -g codehost && codehost setup` does the same. Or, for
+a specific directory/token in one shot:
+
+```bash
+bunx codehost setup ~/my-project -t <token>
+```
+
+Then open **https://codehost.dev**, enter the token printed by `setup`, and your
+server appears in the list. Click **Connect** — VS Code loads in the page,
+served entirely over the peer-to-peer data channel.
+
+> Use `setup` (not `bunx codehost serve`) for the first run: `setup` installs
+> everything and self-heals the native WebRTC module that a bare `bunx` can't
+> fetch on its own.
 
 The `<token>` is a shared secret: anyone with it can see and connect to the
 servers in that room, so treat it like a password. It must be **at least 12
@@ -39,11 +56,25 @@ weaker tokens (e.g. `Str0ng-Token-99`).
 ## CLI
 
 ```bash
+codehost setup [dir] [-t <token>]           # token + VS Code + daemon, one shot
 codehost serve [dir] -t <token> [options]   # serve a directory (default: cwd)
 codehost list                                # list daemonized servers (oxmgr)
 codehost stop <name>                         # stop a daemonized server
+codehost update                              # fetch the latest VS Code CLI now
 ```
 
+**`codehost setup`** is the easy path: it reuses (or generates and saves to
+`~/.codehost/config.json`) a strong room token, ensures a working VS Code,
+starts the server under oxmgr, and prints the token + URL. Pass `-t` to set a
+token explicitly, or `--new-token` to rotate the saved one.
+
+**VS Code is auto-installed.** On first `serve`, codehost uses a `code` already
+on your `PATH` if present; otherwise it downloads Microsoft's standalone VS Code
+CLI for your OS/arch (verifying its sha256), caches it under `~/.codehost/vscode/`,
+and re-checks the stable channel at most once per day. Force a refresh with
+`codehost update`, or point at a specific binary with the `CODEHOST_CODE_BIN`
+environment variable.
+
 `serve` options:
 
 | flag | default | meaning |

package/TODO.md

@@ -0,0 +1,93 @@
+# codehost — TODO / future features
+
+Parked ideas, roughly in priority order. The in-flight deep-link feature
+(`/gh/<owner>/<repo>/tree/<branch>` + `serve`/`dev` split) is tracked in the active
+plan, not here.
+
+## Account login / device auth (Tailscale-style)
+
+Replace/augment bearer tokens with account identity.
+
+- CLI: `codehost serve --login=you@gmail.com` runs a device-authorization flow — prints a
+  short code + URL; you approve in `codehost.dev` while signed in (Google via **Firebase
+  Auth**) as that account. The daemon then holds a credential proving the same identity.
+- Web: sign in with Google (Firebase) on codehost.dev.
+- Signaling Worker: on room join, verify a Firebase ID token / signed JWT for the account
+  instead of (or alongside) the raw token. Personal room is keyed by account, auto-joined
+  by both the daemon and the web client — **no token copy-paste**.
+- Benefits over tokens: revocable per device, per-account isolation, no shared secret to
+  leak. Like Tailscale authenticating devices.
+- Keep **token rooms** too (anonymous quick-share); **login rooms** are the "my own
+  devices" path. The two can coexist.
+- Open questions: Firebase project + Google OAuth client; how the CLI obtains a credential
+  (device-code OAuth vs. a Firebase custom-token minted by the Worker after browser
+  approval); revocation UI; mapping account -> room id.
+
+## Port / service forwarding — `[port|service].f.codehost.dev`
+
+Expose a dev server running on the daemon (the tunnel already proxies HTTP to
+`127.0.0.1:<x>`).
+
+- Needs wildcard DNS `*.f.codehost.dev`, a tiny bootstrap page + its own per-subdomain
+  Service Worker, and a `subdomain -> (room, peer, port)` mapping with token/identity
+  scoping.
+- **Opt-in** registration from a nav/settings panel — do **not** auto-expose every bound
+  port (security footgun).
+
+## Containerized dev environments — `codehost docker up [path]`
+
+Run the workspace inside a container instead of on the host (devcontainer / Codespaces
+style).
+
+- `bunx codehost docker up [path]` mounts `path` into a container, sets up VS Code
+  `serve-web` + the repo's runtime inside (reuse the self-healing `code`/native installers;
+  honor the repo's `.devcontainer/devcontainer.json` when present), and runs the codehost
+  daemon in-container.
+- Access at `codehost.dev/dev/<token>` (or `/gh/...`) via a generated or passed-in token.
+- Lifecycle: `docker up` / `down` / `ps`. Composes with port forwarding above for the
+  container's services.
+- Wins: isolation for untrusted repos, reproducible runtimes, parallel throwaway envs, no
+  host pollution.
+- Open questions: base image (preinstalled `code`+bun vs. self-heal on first run), volume
+  mount perf, how the container daemon gets the token/identity, resource limits.
+
+## agent-yes web terminal UI (over `codehost expose`)
+
+Make `codehost.dev/vs/<peerId>/` actually usable for an exposed agent-yes, not just the raw API.
+
+- Add an HTML/JS terminal UI served by agent-yes's `ts/serve.ts` at `GET /`: xterm in the
+  browser, output via `EventSource('./api/tail/<kw>')` (SSE), input via `POST ./api/send`.
+- **Use relative paths** (`./api/...`) so it works under the tunnel's `/vs/<peerId>/` prefix
+  (the prefix is stripped for the server, but the page's own URLs must stay relative).
+- Reference: **snomiao/wtx** (cloned to lib/wtx) — a Bun PTY WebSocket server with replay
+  buffer + xterm client. Note wtx uses **WebSocket**; agent-yes uses **SSE + POST** — reuse
+  wtx's xterm/client setup but keep agent-yes's transport (or align them).
+- Belongs in the agent-yes repo (it's served by agent-yes), enabled once `codehost expose
+  7432` is running.
+
+## Real-time collaboration / presence (multiplayer cursors)
+
+Multiple people open the same workspace (different Chrome profiles / accounts) and see each
+other's cursors + selections live.
+
+- `serve-web` is single-session: today multiple viewers get independent workbenches with no
+  shared awareness. Needs a layer on top.
+- Realistic path: a **presence/awareness protocol** — each viewer broadcasts identity +
+  cursor/selection over the room substrate we already have (signaling / data channel),
+  rendered as remote-cursor decorations via an injected VS Code extension.
+- Full concurrent co-editing (CRDT/OT, à la Yjs) is a much bigger lift; MS **Live Share** is
+  the off-the-shelf alternative but brings its own backend/auth.
+- Depends on identity (see Account login above) to label who's who.
+
+## Deep-link feature follow-ups (after v1)
+
+- Root daemon **enumerates / existence-checks** the repos under its root (vs. v1's
+  optimistic `?folder=`): nicer discovery list + accurate matching.
+- **Clone-on-demand:** a root daemon `git clone`s `gh/owner/repo` into the root if absent,
+  then opens it (codespaces-like).
+- **Live cross-room search:** fan out across all joined rooms for a repo with no history
+  (multiple concurrent `SignalingClient`s), instead of v1's history-driven single room.
+- **Providers beyond GitHub** (`/gl/...`, self-hosted) via the `provider` field already in
+  `parseDeepLink`.
+- Reflect the active repo back into the URL while browsing; chooser UI when several
+  machines/rooms serve the same repo.

package/docs/vscode-cdn-proxy.md

@@ -0,0 +1,117 @@
+# VS Code CDN proxy (CORS fix)
+
+Status: implemented. Worker side verified; in-browser leg pending a live check.
+
+## Context
+
+When VS Code runs inside the codehost iframe (origin `https://codehost.dev`, served
+over the WebRTC tunnel), its workbench fetches configuration from Microsoft's
+product CDN — e.g. `_fetchChatControlData` does:
+
+```
+fetch('https://main.vscode-cdn.net/extensions/chat.json')
+```
+
+That CDN sends **no `Access-Control-Allow-Origin` header**, so the browser blocks the
+cross-origin read:
+
+```
+Access to fetch at 'https://main.vscode-cdn.net/extensions/chat.json' from origin
+'https://codehost.dev' has been blocked by CORS policy: No 'Access-Control-Allow-Origin'
+header is present on the requested resource.
+```
+
+Our Service Worker only handled same-origin requests (it early-returned on
+cross-origin), so these went straight to the CDN and failed. Chat / built-in-extension
+control data never loaded and the console filled with CORS errors.
+
+A Service Worker **alone cannot fix this**: it runs in the browser, bound by the same
+CORS rules, and cannot turn a no-CORS cross-origin body into a readable one. The fix
+needs a server-side proxy that re-serves the bytes with permissive CORS, plus a small
+SW change to route the request there.
+
+## Decision
+
+Reuse the already-deployed **signaling Worker** (`worker/index.ts`, served at
+`signal.<page-host>`) as a thin, allow-listed CDN proxy. The Service Worker rewrites
+blocked CDN requests to it.
+
+```
+VS Code iframe (codehost.dev)                signaling Worker (signal.codehost.dev)
+  fetch main.vscode-cdn.net/extensions/chat.json
+        │  (cross-origin, CORS-blocked)
+        ▼
+  Service Worker (sw.ts)
+    host ends with .vscode-cdn.net ?  ──rewrite──►  GET /cdn/main.vscode-cdn.net/extensions/chat.json
+    cache.match() first, else fetch + cache.put()        │  allow-list check (.vscode-cdn.net)
+        ▲                                                 │  fetch upstream (server-side, not CORS-bound)
+        └──────────── readable response ◄────────────────┘  + Access-Control-Allow-Origin: *
+                                                            + preserve content-type, edge-cache
+```
+
+**Self-host constraint (important):** the SW targets the **derived** signaling host
+(`signal.<current page host>`), never a hardcoded `signal.codehost.dev`. A self-hoster
+who serves the page + Worker on their own domain is automatically proxied by their own
+Worker at `signal.<their-domain>/cdn/...`, with no code changes. See
+`cdnProxyBase(hostname, protocol)` in `src/web/config.ts`.
+
+## Alternatives considered
+
+- **Cloudflare Pages Function on `codehost.dev`** — same-origin and clean, but adds
+  Pages Functions to the currently pure-static build/deploy for no gain over reusing the
+  Worker we already run.
+- **Daemon proxy over the WebRTC tunnel** — most self-host-robust (the daemon is always
+  the user's own machine, works even on networks where the browser can't reach the edge)
+  and zero hosted cost. Rejected as the default because it is slower (MS → daemon →
+  WebRTC → browser), cannot share a cache across users, adds CDN bytes to the WebRTC
+  datachannel, and allow-list changes must ship a new CLI to every user. The Worker wins
+  on latency, shared edge caching, and one-deploy allow-list updates. Cost is ~$0:
+  Cloudflare bills no egress, and these assets are tiny, public, and cacheable.
+
+If a fully air-gapped / browser-can't-reach-the-edge deployment ever matters, the daemon
+proxy is the fallback to revisit.
+
+## Security
+
+- The Worker is the **authoritative allow-list**: only hosts ending in `.vscode-cdn.net`
+  are proxied (`CDN_HOST_SUFFIX` in `worker/index.ts`). Anything else → `403`. The
+  leading dot prevents look-alikes like `notvscode-cdn.net`.
+- **GET/HEAD only** (others → `405`). It forwards a path under the chosen host and never
+  follows attacker-controlled hostnames, so it is not an open proxy.
+- The SW's suffix check (`isProxiableCdnHost` in `src/web/config.ts`) is only an
+  optimization deciding what to rewrite; if it ever drifts from the Worker's list, the
+  worst case is a `403` or an unproxied request — the Worker stays the real gate.
+
+## Extending the allow-list
+
+If the workbench starts pulling from another host (e.g. `update.code.visualstudio.com`),
+widen the gate in two places and redeploy (one Worker + one Pages deploy — no CLI
+change):
+
+- `worker/index.ts` — `CDN_HOST_SUFFIX` (or make it a small list of suffixes).
+- `src/web/config.ts` — `VSCODE_CDN_SUFFIX` / `isProxiableCdnHost`.
+
+The extension **marketplace** (install/search) is a separate, larger concern (auth,
+large payloads) and is intentionally out of scope here.
+
+## Files
+
+- `worker/index.ts` — `/cdn/<host>/<path>` route + `handleCdnProxy` (allow-list, CORS,
+  `caches.default` edge cache, `content-type` passthrough, `cache-control`).
+- `src/web/sw.ts` — cross-origin branch → `proxyCdn` (rewrite to the derived `/cdn`
+  base, Cache API per-browser caching).
+- `src/web/config.ts` — `cdnProxyBase`, `isProxiableCdnHost`, `VSCODE_CDN_SUFFIX`
+  (shared host derivation, reused by `getSignalUrl`).
+
+## Verification
+
+- **Worker, direct (done):**
+  - `curl -i https://signal.codehost.dev/cdn/main.vscode-cdn.net/extensions/chat.json`
+    → `200`, `content-type: application/json`, `access-control-allow-origin: *`,
+    `cache-control: public, max-age=3600`, real JSON body.
+  - `…/cdn/evil.example.com/x` → `403`; `POST …` → `405`.
+- **In-browser (pending live check):** open `codehost.dev` (SW active), then from the
+  page `fetch('https://main.vscode-cdn.net/extensions/chat.json')` should resolve `200`
+  (served via `signal.<host>/cdn/...`) instead of throwing a CORS error; a second call is
+  served from the SW cache. Then load VS Code in the iframe and confirm the `chat.json`
+  CORS error is gone from the console.

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "codehost",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/snomiao/codehost.git"
+  },
+  "homepage": "https://codehost.dev",
+  "bugs": "https://github.com/snomiao/codehost/issues",
   "bin": {
     "codehost": "./src/cli/index.ts"
   },
@@ -27,11 +33,15 @@
     "bun-pty": "^0.4.8",
     "hono": "^4.12.16",
     "node-datachannel": "^0.32.3",
+    "oxmgr": "^0.4.0",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "yargs": "^17.7.2"
   },
   "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "semantic-release": "^25.0.0",
     "@types/bun": "^1.3.0",
     "@types/react": "^19.1.9",
     "@types/react-dom": "^19.1.7",

package/public/_redirects

@@ -0,0 +1,5 @@
+# SPA fallback: deep links like /gh/<owner>/<repo>/tree/<branch> and /dev/<path>
+# have no static file, so serve the app and let it route client-side. Cloudflare
+# Pages serves existing files first (/assets/*, /sw.js, /install.*), so only
+# unmatched paths hit this rule. /vs/* is handled by the Service Worker at runtime.
+/*  /index.html  200

package/public/install.ps1

@@ -0,0 +1,43 @@
+# codehost installer — https://codehost.dev
+#
+#   powershell -c "irm codehost.dev/install.ps1 | iex"
+#
+# Ensures Bun is installed, installs the `codehost` CLI globally (which fetches
+# the native WebRTC binary via Bun's lifecycle scripts), then runs `codehost
+# setup` to pick a token, install VS Code, and start a server daemon.
+#
+# Env override: $env:CODEHOST_NO_SETUP = "1"  -> install only, skip setup.
+
+$ErrorActionPreference = "Stop"
+
+function Info($m) { Write-Host "[codehost] $m" -ForegroundColor Cyan }
+function Fail($m) { Write-Host "[codehost] $m" -ForegroundColor Red; exit 1 }
+
+# Bun installs its global bin under %USERPROFILE%\.bun\bin by default.
+$bunBin = Join-Path $env:USERPROFILE ".bun\bin"
+if (Test-Path $bunBin) { $env:Path = "$bunBin;$env:Path" }
+
+if (-not (Get-Command bun -ErrorAction SilentlyContinue)) {
+  Info "Bun not found - installing from bun.sh..."
+  Invoke-RestMethod https://bun.sh/install.ps1 | Invoke-Expression
+  if (Test-Path $bunBin) { $env:Path = "$bunBin;$env:Path" }
+}
+
+if (-not (Get-Command bun -ErrorAction SilentlyContinue)) {
+  Fail "Bun install did not land on PATH. Open a new terminal and re-run."
+}
+
+Info "installing the codehost CLI (bun add -g codehost)..."
+bun add -g codehost
+
+if (-not (Get-Command codehost -ErrorAction SilentlyContinue)) {
+  Fail "codehost installed but not on PATH. Add $bunBin to PATH and run: codehost setup"
+}
+
+if ($env:CODEHOST_NO_SETUP -eq "1") {
+  Info "installed. Run ``codehost setup`` in the directory you want to serve."
+  exit 0
+}
+
+Info "running ``codehost setup``..."
+codehost setup

package/public/install.sh

@@ -0,0 +1,55 @@
+#!/bin/sh
+# codehost installer — https://codehost.dev
+#
+#   curl -fsSL https://codehost.dev/install.sh | sh
+#
+# Ensures Bun is installed, installs the `codehost` CLI globally (which fetches
+# the native WebRTC binary via Bun's lifecycle scripts), then runs `codehost
+# setup` to pick a token, install VS Code, and start a server daemon.
+#
+# Env overrides:
+#   CODEHOST_NO_SETUP=1   install only; don't run `codehost setup`
+set -eu
+
+info() { printf '\033[1;36m[codehost]\033[0m %s\n' "$1"; }
+err()  { printf '\033[1;31m[codehost]\033[0m %s\n' "$1" >&2; }
+
+# Bun installs its global bin here by default; make sure it's on PATH for both
+# the bun we may install and the `codehost` we're about to install.
+BUN_INSTALL="${BUN_INSTALL:-$HOME/.bun}"
+export BUN_INSTALL
+export PATH="$BUN_INSTALL/bin:$PATH"
+
+if ! command -v bun >/dev/null 2>&1; then
+  info "Bun not found — installing from bun.sh…"
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL https://bun.sh/install | bash
+  elif command -v wget >/dev/null 2>&1; then
+    wget -qO- https://bun.sh/install | bash
+  else
+    err "need curl or wget to install Bun. Install one and re-run."
+    exit 1
+  fi
+  export PATH="$BUN_INSTALL/bin:$PATH"
+fi
+
+if ! command -v bun >/dev/null 2>&1; then
+  err "Bun install did not land on PATH. Open a new shell or add $BUN_INSTALL/bin to PATH, then re-run."
+  exit 1
+fi
+
+info "installing the codehost CLI (bun add -g codehost)…"
+bun add -g codehost
+
+if ! command -v codehost >/dev/null 2>&1; then
+  err "codehost installed but not on PATH. Add $BUN_INSTALL/bin to your PATH and run: codehost setup"
+  exit 1
+fi
+
+if [ "${CODEHOST_NO_SETUP:-}" = "1" ]; then
+  info "installed. Run \`codehost setup\` in the directory you want to serve."
+  exit 0
+fi
+
+info "running \`codehost setup\`…"
+exec codehost setup

package/src/cli/commands/dev.ts

@@ -0,0 +1,107 @@
+import { hostname } from "node:os";
+import { resolve } from "node:path";
+import type { CommandModule } from "yargs";
+import type { PeerMeta } from "../../shared/signaling";
+import { TOKEN_REQUIREMENTS, validateToken } from "../../shared/token";
+import { launchServeDaemon } from "../daemonize";
+import { announceConnect } from "../open-url";
+import { runServer } from "../run-server";
+import { launchVscode } from "../vscode";
+import { repoIdentity } from "../git";
+import { DEFAULT_SIGNAL_URL } from "./serve";
+
+interface DevArgs {
+  dir: string;
+  token: string;
+  name?: string;
+  signal: string;
+  daemon: boolean;
+  port?: number;
+}
+
+export const devCommand: CommandModule<{}, DevArgs> = {
+  command: "dev [dir]",
+  describe:
+    "Serve a single folder over WebRTC; open it at codehost.dev/dev/<path> (or /gh/<owner>/<repo> when it's a GitHub repo)",
+  builder: (y) =>
+    y
+      .positional("dir", {
+        describe: "Directory to serve (defaults to cwd)",
+        type: "string",
+        default: ".",
+      })
+      .option("token", {
+        alias: "t",
+        describe: "Room token shared with the codehost.dev page",
+        type: "string",
+        demandOption: true,
+      })
+      .option("name", {
+        describe: "Display name for this server (defaults to hostname)",
+        type: "string",
+      })
+      .option("signal", {
+        describe: "Signaling server URL",
+        type: "string",
+        default: DEFAULT_SIGNAL_URL,
+      })
+      .option("daemon", {
+        alias: "d",
+        describe: "Run in the background under oxmgr (auto-starts on login)",
+        type: "boolean",
+        default: false,
+      })
+      .option("port", {
+        describe: "Fixed port for the local VS Code server (default: ephemeral)",
+        type: "number",
+      }) as any,
+  handler: async (argv) => {
+    argv.token = argv.token.trim();
+    const check = validateToken(argv.token);
+    if (!check.ok) {
+      console.error(`[codehost] ${check.reason}`);
+      console.error(`[codehost] room token requires: ${TOKEN_REQUIREMENTS}`);
+      process.exit(1);
+    }
+
+    const dir = resolve(process.cwd(), argv.dir);
+    const host = hostname();
+
+    if (argv.daemon) {
+      const { ok } = await launchServeDaemon({
+        command: "dev",
+        dir,
+        token: argv.token,
+        signal: argv.signal,
+        name: argv.name,
+        port: argv.port,
+        host,
+      });
+      if (ok) announceConnect(argv.token);
+      process.exit(ok ? 0 : 1);
+    }
+
+    // A single folder: git-identified so GitHub deep links resolve to it.
+    const id = repoIdentity(dir);
+    const meta: PeerMeta = {
+      name: argv.name ?? host,
+      cwd: dir,
+      host,
+      kind: "repo",
+      repo: id.repo,
+      branch: id.branch,
+    };
+
+    announceConnect(argv.token);
+    await runServer({
+      token: argv.token,
+      signal: argv.signal,
+      meta,
+      label: `serving ${dir}`,
+      launch: async (basePath) => {
+        const v = await launchVscode({ dir, basePath, port: argv.port });
+        return { port: v.port, stop: v.stop };
+      },
+    });
+  },
+};