codehost 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+# [0.16.0](https://github.com/snomiao/codehost/compare/v0.15.0...v0.16.0) (2026-06-10)
+
+
+### Features
+
+* **provision:** codehost init scaffolds .codehost/ (config + setup hooks) ([b1a2e9c](https://github.com/snomiao/codehost/commit/b1a2e9c23230e09dc6a291dbcab098083bb59f4d))
+* **provision:** daemon-side provision handler over the tunnel ([c297e95](https://github.com/snomiao/codehost/commit/c297e9577b3e1a65260ab105478feb63186fce46))
+* **provision:** tested security core for workspace provisioning ([ca7508c](https://github.com/snomiao/codehost/commit/ca7508c48e78eb46fbf8bf42ef398360bea38f86))
+* **web:** provisioning browser flow — run setup.sh on repo open, stream log ([9bd8742](https://github.com/snomiao/codehost/commit/9bd8742b143e84d386f8af138df73e57cac70e46))
+
+# [0.15.0](https://github.com/snomiao/codehost/compare/v0.14.0...v0.15.0) (2026-06-10)
+
+
+### Features
+
+* **web:** 'open a GitHub URL' box + deepest-root repo resolution ([0d9ebec](https://github.com/snomiao/codehost/commit/0d9ebec4409430c327e2945657b6803ca704fd53))
+
 # [0.14.0](https://github.com/snomiao/codehost/compare/v0.13.0...v0.14.0) (2026-06-10)
 
 

package/docs/provisioning.md

@@ -0,0 +1,130 @@
+# Workspace provisioning
+
+Status: **design / proposal** (not implemented). Captures the design discussed
+for "open a repo link → the workspace materializes on the host".
+
+## Goal
+
+Opening a repo deep link should *materialize* the workspace on the serving host
+on demand — clone / worktree-add / install — instead of requiring it to already
+exist. Today, opening `/gh/<owner>/<repo>/tree/<branch>` when that worktree isn't
+present just fails (`serve-web` reports "workspace does not exist").
+
+The host owner stays in control: all provisioning is a **user-authored,
+idempotent script** on the host. codehost never invents commands.
+
+## Model
+
+`codehost serve` runs in a *home* directory (`$HOME_ROOT`):
+
+```
+$HOME_ROOT/
+├── .codehost/                  # config dir — edited in VS Code itself
+│   ├── config.yaml             # settings (workspace path template, allowlist…)
+│   ├── setup.sh / setup.bat    # idempotent provisioning, run on every open
+│   └── …                       # any other files the user keeps here
+└── ws/                         # default workspaces root (redefinable in config.yaml)
+    └── <owner>/<repo>/tree/<branch>/
+```
+
+- `.codehost/` is the config folder. `ws/` is where github-shaped paths land.
+- Default layout: `ws/{owner}/{repo}/tree/{branch}` (the `tree/<branch>` worktree
+  convention — branches are real side-by-side directories).
+- The workspace path is redefinable in `config.yaml`.
+
+## Open flow
+
+```
+open /gh/<owner>/<repo>/tree/<branch>
+  → daemon runs .codehost/setup.sh with owner/repo/branch (+ host)
+       setup.sh decides: clone / git worktree add / pull / rebase / skip
+       (idempotent — the policy, incl. auto-upgrade/rebase, is the user's)
+  → VS Code opens the resulting workspace path
+```
+
+Because `setup.sh` is idempotent and runs **every** time, codehost does not track
+clone state at all — the script clones if missing, fast-skips if present, and the
+user decides whether to auto-pull/rebase. This removes a lot of codehost logic.
+
+## `setup.sh` contract
+
+- **Input** (env, never interpolated into a command string):
+  `CODEHOST_OWNER`, `CODEHOST_REPO`, `CODEHOST_BRANCH`, `CODEHOST_HOST`,
+  `CODEHOST_HOME` (the home root), `CODEHOST_WS` (the resolved default path from
+  the `config.yaml` template).
+- **Output**: the absolute workspace path on stdout (last line). If it prints
+  nothing, codehost uses `CODEHOST_WS` (the template default).
+- **Exit non-zero** → provisioning failed; surface the error to the browser.
+- Must be **idempotent** and fast on an already-provisioned path (skip).
+- **Windows**: `setup.bat` (or pwsh) with the same env contract.
+
+## `config.yaml` (sketch)
+
+```yaml
+workspace: "ws/{owner}/{repo}/tree/{branch}"   # path template, relative to home
+allowlist:                                      # which repos may auto-provision
+  - github.com/snomiao/*
+# …future: default branch, install hook, etc.
+```
+
+## Reuse VS Code for config (no custom UI)
+
+Editing config = open `$HOME_ROOT/.codehost/` in the **existing VS Code iframe**.
+A "Config" affordance in the header opens `?folder=<home>/.codehost`. No
+`/p/<peer-id>/` settings page, no re-invented editor. (Peer ids are ephemeral —
+they change on every daemon restart — so config is keyed by the host/home, not
+the peer.)
+
+## Create-from-GitHub input box
+
+On the workspace list page, an input: **paste a GitHub URL**.
+
+```
+https://github.com/snomiao/codehost/tree/main
+  → parse → /gh/snomiao/codehost/tree/main → open (triggers provisioning)
+```
+
+One paste opens any GitHub repo on a connected host (= "create workspace from
+GitHub"). Accepts bare `github.com/<owner>/<repo>` and `…/tree/<branch>` forms.
+
+## Provisioning UX
+
+- While `setup.sh` runs, show a **"provisioning…"** state with the script's
+  stdout/stderr **streamed over the tunnel** (clone/install can take a while).
+- Idempotent re-opens skip and are near-instant.
+
+## Security (the crux)
+
+- **Commands are host-authored** (`setup.sh` lives on the host). The link/viewer
+  supplies only `owner/repo/branch` identity — never commands.
+- codehost **sanitizes** `owner/repo/branch` before handing them to `setup.sh`
+  (reject `;`, `$()`, backticks, newlines, `..`, path separators where not
+  expected) and passes them as **env**, not string-interpolated into a command.
+- **allowlist** (`config.yaml` / `setup.sh`) gates which repos auto-provision;
+  others prompt or are denied.
+- Any room member can trigger `setup.sh` with any identity, so the **room token
+  is the trust boundary** and `setup.sh`/allowlist owns repo policy. Editing
+  config (= changing what runs on the host) may warrant owner auth beyond the
+  room token — open question.
+
+## Defaults / scaffolding
+
+- No `.codehost/setup.sh` → fall back to today's behavior (resolve to the layout
+  path, no clone).
+- `codehost init` scaffolds a starter `.codehost/` (`config.yaml` + a `setup.sh`
+  that does `gh repo clone` + `git worktree add` + the `ws/` convention).
+
+## Related fix (independent, same path)
+
+`resolveRepoTarget` picks the *first* root daemon without checking which one
+actually contains the repo, so with multiple roots it can pick the wrong one
+(observed live: it chose `/Users/sno` over the correct `/Users/sno/ws`, yielding
+a non-existent subpath). Prefer the **deepest matching root** (longest `cwd`
+prefix). Not part of provisioning, but it gates the same "open a repo" path.
+
+## Open questions
+
+1. Source of truth for the path: `setup.sh` stdout vs `config.yaml` template.
+   (Proposed: stdout wins; the template is the default handed in as `CODEHOST_WS`.)
+2. Owner auth for editing config beyond the room token?
+3. Log streaming transport: a new tunnel channel vs reuse of an existing one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codehost",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -38,6 +38,7 @@
     "oxmgr": "^0.4.0",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
+    "yaml": "^2.9.0",
     "yargs": "^17.7.2"
   },
   "devDependencies": {

package/src/cli/commands/init.ts

@@ -0,0 +1,27 @@
+import { resolve } from "node:path";
+import type { CommandModule } from "yargs";
+import { scaffoldCodehost } from "../init";
+
+interface InitArgs {
+  dir: string;
+  force: boolean;
+}
+
+export const initCommand: CommandModule<{}, InitArgs> = {
+  command: "init [dir]",
+  describe: "Scaffold .codehost/ (config.yaml + setup.sh) so repo links auto-provision",
+  builder: (y) =>
+    y
+      .positional("dir", { describe: "Home dir to scaffold (defaults to cwd)", type: "string", default: "." })
+      .option("force", { alias: "f", describe: "Overwrite existing files", type: "boolean", default: false }) as any,
+  handler: (argv) => {
+    const dir = resolve(process.cwd(), argv.dir);
+    const written = scaffoldCodehost(dir, argv.force);
+    if (written.length === 0) {
+      console.log(`[codehost] .codehost/ already set up in ${dir} (use --force to overwrite)`);
+      return;
+    }
+    console.log(`[codehost] scaffolded:\n${written.map((p) => `  ${p}`).join("\n")}`);
+    console.log(`[codehost] edit .codehost/setup.sh, then run: codehost serve ${dir}`);
+  },
+};

package/src/cli/commands/serve.ts

@@ -2,7 +2,7 @@ import { hostname } from "node:os";
 import { resolve } from "node:path";
 import type { CommandModule } from "yargs";
 import type { PeerMeta } from "../../shared/signaling";
-import { DEFAULT_LAYOUT, toPosixPath } from "../../shared/repo";
+import { DEFAULT_LAYOUT, GITHUB_HOST, toPosixPath } from "../../shared/repo";
 import { TOKEN_REQUIREMENTS, validateToken } from "../../shared/token";
 import { launchServeDaemon } from "../daemonize";
 import { announceConnect } from "../open-url";
@@ -101,6 +101,7 @@ export const serveCommand: CommandModule<{}, ServeArgs> = {
       signal: argv.signal,
       meta,
       label: `serving workspace root ${dir}`,
+      provision: { homeDir: dir, host: GITHUB_HOST },
       launch: async (basePath) => {
         const v = await launchVscode({ dir, basePath, port: argv.port });
         return { port: v.port, stop: v.stop };

package/src/cli/index.ts

@@ -2,6 +2,7 @@
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { setupCommand } from "./commands/setup";
+import { initCommand } from "./commands/init";
 import { serveCommand } from "./commands/serve";
 import { devCommand } from "./commands/dev";
 import { exposeCommand } from "./commands/expose";
@@ -14,6 +15,7 @@ yargs(hideBin(process.argv))
   .scriptName("codehost")
   .usage("$0 <command> [options]")
   .command(setupCommand)
+  .command(initCommand)
   .command(serveCommand)
   .command(devCommand)
   .command(exposeCommand)

package/src/cli/init.test.ts

@@ -0,0 +1,48 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { scaffoldCodehost } from "./init";
+
+const homes: string[] = [];
+afterAll(() => homes.forEach((h) => rmSync(h, { recursive: true, force: true })));
+function mkHome(): string {
+  const h = mkdtempSync(join(tmpdir(), "codehost-init-"));
+  homes.push(h);
+  return h;
+}
+
+describe("scaffoldCodehost", () => {
+  test("writes config.yaml + setup.sh + setup.ps1", () => {
+    const home = mkHome();
+    const written = scaffoldCodehost(home);
+    expect(written).toHaveLength(3);
+    expect(existsSync(join(home, ".codehost", "config.yaml"))).toBe(true);
+    expect(existsSync(join(home, ".codehost", "setup.sh"))).toBe(true);
+    expect(existsSync(join(home, ".codehost", "setup.ps1"))).toBe(true);
+  });
+
+  test("config.yaml is valid YAML with a workspace template", () => {
+    const home = mkHome();
+    scaffoldCodehost(home);
+    const cfg = parseYaml(readFileSync(join(home, ".codehost", "config.yaml"), "utf8"));
+    expect(cfg.workspace).toBe("ws/{owner}/{repo}/tree/{branch}");
+  });
+
+  test("setup.sh keeps shell vars literal (no JS interpolation leaked)", () => {
+    const home = mkHome();
+    scaffoldCodehost(home);
+    const sh = readFileSync(join(home, ".codehost", "setup.sh"), "utf8");
+    expect(sh).toContain("$CODEHOST_WS");
+    expect(sh).toContain("${ws%/tree/$CODEHOST_BRANCH}");
+    expect(sh).toContain("git -C \"$repo\" worktree add");
+  });
+
+  test("idempotent: a second run writes nothing; --force overwrites", () => {
+    const home = mkHome();
+    expect(scaffoldCodehost(home)).toHaveLength(3);
+    expect(scaffoldCodehost(home)).toHaveLength(0);
+    expect(scaffoldCodehost(home, true)).toHaveLength(3);
+  });
+});

package/src/cli/init.ts

@@ -0,0 +1,103 @@
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Scaffolds a home's `.codehost/` config dir: an editable, idempotent setup hook
+// (run on every repo open) plus a config.yaml. Provisioning is opt-in by these
+// files existing — `codehost init` is how you opt in.
+
+const CONFIG_YAML = `# codehost workspace config — see docs/provisioning.md
+
+# Where /gh/<owner>/<repo>/tree/<branch> lands, relative to this home dir.
+# Default (if omitted): {owner}/{repo}/tree/{branch}
+workspace: "ws/{owner}/{repo}/tree/{branch}"
+
+# Optional: only these repos may auto-provision (a trailing /* is an owner
+# wildcard). Empty/absent = allow all. The room token already grants access, so
+# this is extra hardening, not the primary gate.
+# allowlist:
+#   - github.com/snomiao/*
+`;
+
+const SETUP_SH = `#!/usr/bin/env bash
+# codehost provisioning hook. Runs on every open of /gh/<owner>/<repo>/tree/<branch>
+# BEFORE the editor opens CODEHOST_WS. Keep it idempotent: clone/worktree if
+# missing, fast-skip if present. Edit freely (install deps, pull/rebase policy…).
+#
+# Env in:  CODEHOST_OWNER  CODEHOST_REPO  CODEHOST_BRANCH  CODEHOST_HOST
+#          CODEHOST_HOME (this dir)       CODEHOST_WS (the path the editor opens)
+set -euo pipefail
+
+ws="$CODEHOST_WS"
+if [ -e "$ws/.git" ]; then
+  echo "[setup] $ws already provisioned"
+  exit 0
+fi
+
+# Primary clone = the workspace path minus the /tree/<branch> tail (layout-agnostic).
+repo="\${ws%/tree/$CODEHOST_BRANCH}"
+url="https://$CODEHOST_HOST/$CODEHOST_OWNER/$CODEHOST_REPO.git"
+
+if [ ! -e "$repo/.git" ]; then
+  echo "[setup] cloning $url"
+  mkdir -p "$(dirname "$repo")"
+  git clone "$url" "$repo"
+fi
+
+echo "[setup] adding worktree $ws @ $CODEHOST_BRANCH"
+mkdir -p "$(dirname "$ws")"
+git -C "$repo" fetch --quiet origin "$CODEHOST_BRANCH" || true
+git -C "$repo" worktree add "$ws" "$CODEHOST_BRANCH" \\
+  || git -C "$repo" worktree add -b "$CODEHOST_BRANCH" "$ws" "origin/$CODEHOST_BRANCH"
+
+# Example: install deps for this worktree (uncomment / edit).
+# ( cd "$ws" && bun install )
+
+echo "[setup] ready: $ws"
+`;
+
+const SETUP_PS1 = `# codehost provisioning hook (Windows). See setup.sh for the contract.
+$ErrorActionPreference = "Stop"
+$ws = $env:CODEHOST_WS
+if (Test-Path (Join-Path $ws ".git")) { Write-Host "[setup] $ws already provisioned"; exit 0 }
+
+$repo = $ws -replace "[\\\\/]tree[\\\\/]$([regex]::Escape($env:CODEHOST_BRANCH))$", ""
+$url = "https://$($env:CODEHOST_HOST)/$($env:CODEHOST_OWNER)/$($env:CODEHOST_REPO).git"
+
+if (-not (Test-Path (Join-Path $repo ".git"))) {
+  Write-Host "[setup] cloning $url"
+  New-Item -ItemType Directory -Force -Path (Split-Path $repo) | Out-Null
+  git clone $url $repo
+}
+Write-Host "[setup] adding worktree $ws @ $($env:CODEHOST_BRANCH)"
+New-Item -ItemType Directory -Force -Path (Split-Path $ws) | Out-Null
+git -C $repo worktree add $ws $env:CODEHOST_BRANCH
+Write-Host "[setup] ready: $ws"
+`;
+
+const FILES: Array<{ rel: string; body: string; exec?: boolean }> = [
+  { rel: "config.yaml", body: CONFIG_YAML },
+  { rel: "setup.sh", body: SETUP_SH, exec: true },
+  { rel: "setup.ps1", body: SETUP_PS1 },
+];
+
+/** Write `<homeDir>/.codehost/{config.yaml,setup.sh,setup.ps1}`. Existing files
+ *  are kept unless `force`. Returns the list of files actually written. */
+export function scaffoldCodehost(homeDir: string, force = false): string[] {
+  const dir = join(homeDir, ".codehost");
+  mkdirSync(dir, { recursive: true });
+  const written: string[] = [];
+  for (const f of FILES) {
+    const path = join(dir, f.rel);
+    if (existsSync(path) && !force) continue;
+    writeFileSync(path, f.body);
+    if (f.exec) {
+      try {
+        chmodSync(path, 0o755);
+      } catch {
+        // non-POSIX fs — ignore
+      }
+    }
+    written.push(path);
+  }
+  return written;
+}

package/src/cli/provision-server.test.ts

@@ -0,0 +1,76 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { handleProvision, isProvisionPath } from "./provision-server";
+
+// A throwaway home with an optional .codehost/setup.sh.
+function makeHome(setup?: string, configYaml?: string): string {
+  const home = mkdtempSync(join(tmpdir(), "codehost-prov-"));
+  if (setup || configYaml) mkdirSync(join(home, ".codehost"), { recursive: true });
+  if (setup) writeFileSync(join(home, ".codehost", "setup.sh"), setup);
+  if (configYaml) writeFileSync(join(home, ".codehost", "config.yaml"), configYaml);
+  homes.push(home);
+  return home;
+}
+const homes: string[] = [];
+afterAll(() => homes.forEach((h) => rmSync(h, { recursive: true, force: true })));
+
+const q = (owner: string, repo: string, branch = "main") =>
+  `/__codehost/provision?owner=${owner}&repo=${repo}&branch=${branch}`;
+
+describe("isProvisionPath", () => {
+  test("matches the route, ignores query + other paths", () => {
+    expect(isProvisionPath("/__codehost/provision?owner=a")).toBe(true);
+    expect(isProvisionPath("/vs/abc/?folder=x")).toBe(false);
+  });
+});
+
+describe("handleProvision", () => {
+  test("no setup script → 200 + workspace path in header/body (today's behavior)", async () => {
+    const home = makeHome();
+    const res = await handleProvision(q("snomiao", "codehost"), { homeDir: home, host: "github.com" });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("x-codehost-workspace")).toBe(`${home}/snomiao/codehost/tree/main`);
+    expect(await res.json()).toEqual({ workspace: `${home}/snomiao/codehost/tree/main` });
+  });
+
+  test("runs setup.sh, streams output + exit sentinel, env is passed", async () => {
+    const home = makeHome('echo "owner=$CODEHOST_OWNER branch=$CODEHOST_BRANCH ws=$CODEHOST_WS"\nexit 0\n');
+    const res = await handleProvision(q("snomiao", "codehost", "feat/x"), { homeDir: home, host: "github.com" });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("x-codehost-workspace")).toBe(`${home}/snomiao/codehost/tree/feat/x`);
+    const body = await res.text();
+    expect(body).toContain(`owner=snomiao branch=feat/x ws=${home}/snomiao/codehost/tree/feat/x`);
+    expect(body).toContain("::codehost:exit=0");
+  });
+
+  test("propagates a non-zero exit code in the sentinel", async () => {
+    const home = makeHome('echo "boom" >&2\nexit 7\n');
+    const res = await handleProvision(q("snomiao", "codehost"), { homeDir: home, host: "github.com" });
+    const body = await res.text();
+    expect(body).toContain("boom");
+    expect(body).toContain("::codehost:exit=7");
+  });
+
+  test("rejects a traversal identity with 400 (no spawn)", async () => {
+    const home = makeHome("echo SHOULD_NOT_RUN\nexit 0\n");
+    const res = await handleProvision(q("..", "codehost"), { homeDir: home, host: "github.com" });
+    expect(res.status).toBe(400);
+    expect(await res.text()).not.toContain("SHOULD_NOT_RUN");
+  });
+
+  test("enforces the config allowlist with 403", async () => {
+    const home = makeHome("echo hi\nexit 0\n", "allowlist:\n  - github.com/snomiao/*\n");
+    const ok = await handleProvision(q("snomiao", "codehost"), { homeDir: home, host: "github.com" });
+    expect(ok.status).toBe(200);
+    const denied = await handleProvision(q("evil", "repo"), { homeDir: home, host: "github.com" });
+    expect(denied.status).toBe(403);
+  });
+
+  test("config.yaml workspace template overrides the layout", async () => {
+    const home = makeHome(undefined, 'workspace: "ws/{owner}/{repo}/tree/{branch}"\n');
+    const res = await handleProvision(q("snomiao", "codehost"), { homeDir: home, host: "github.com" });
+    expect(res.headers.get("x-codehost-workspace")).toBe(`${home}/ws/snomiao/codehost/tree/main`);
+  });
+});

package/src/cli/provision-server.ts

@@ -0,0 +1,178 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { repoAllowed, resolveWorkspacePath, validateProvisionTarget, type ProvisionTarget } from "../shared/provision";
+import { fromPosixPath, repoKey, toPosixPath } from "../shared/repo";
+
+// Daemon side of provisioning. A repo open hits `GET /__codehost/provision?...`
+// over the tunnel; this validates the identity, computes the daemon-authoritative
+// workspace path, and (if `.codehost/setup.sh` exists) runs it, streaming its
+// output back as the response body. The resolved path rides in the
+// `x-codehost-workspace` header so it never depends on parsing script output.
+
+export const PROVISION_PATH = "/__codehost/provision";
+const TIMEOUT_MS = Number(process.env.CODEHOST_PROVISION_TIMEOUT_MS) || 15 * 60_000;
+
+export interface ProvisionDeps {
+  /** Real OS path of the served home root. */
+  homeDir: string;
+  /** Git host advertised by this daemon (default github.com). */
+  host: string;
+}
+
+interface CodehostConfig {
+  workspace?: string; // layout template, e.g. "ws/{owner}/{repo}/tree/{branch}"
+  allowlist?: string[];
+}
+
+/** True for the provision route (ignoring the query string). */
+export function isProvisionPath(path: string): boolean {
+  return path.split("?")[0] === PROVISION_PATH;
+}
+
+function readConfig(homeDir: string): CodehostConfig {
+  try {
+    const raw = readFileSync(join(homeDir, ".codehost", "config.yaml"), "utf8");
+    const c = (parseYaml(raw) ?? {}) as Record<string, unknown>;
+    return {
+      workspace: typeof c.workspace === "string" ? c.workspace : undefined,
+      allowlist: Array.isArray(c.allowlist)
+        ? c.allowlist.filter((x): x is string => typeof x === "string")
+        : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** Locate the host's setup script (platform-appropriate), or null if none — in
+ *  which case provisioning is a no-op and we just return the path. */
+function findSetupScript(homeDir: string): string[] | null {
+  const dir = join(homeDir, ".codehost");
+  if (process.platform === "win32") {
+    const bat = join(dir, "setup.bat");
+    if (existsSync(bat)) return ["cmd", "/c", bat];
+    const ps1 = join(dir, "setup.ps1");
+    if (existsSync(ps1)) return ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", ps1];
+  }
+  const sh = join(dir, "setup.sh");
+  if (existsSync(sh)) return ["bash", sh];
+  return null;
+}
+
+// Per-workspace coalescing: a concurrent open of the same target waits for the
+// running provision instead of spawning a second one.
+const inFlight = new Map<string, Promise<number>>();
+
+export async function handleProvision(rawPath: string, deps: ProvisionDeps): Promise<Response> {
+  const url = new URL(`http://x${rawPath}`);
+  const v = validateProvisionTarget(
+    url.searchParams.get("owner") ?? "",
+    url.searchParams.get("repo") ?? "",
+    url.searchParams.get("branch") ?? "",
+  );
+  if (!v.ok) return json(400, { error: v.reason });
+
+  const host = (url.searchParams.get("host") ?? deps.host).toLowerCase();
+  const cfg = readConfig(deps.homeDir);
+  const key = repoKey({ host, owner: v.target.owner, name: v.target.repo });
+  if (!repoAllowed(key, cfg.allowlist)) return json(403, { error: `repo not allowlisted: ${key}` });
+
+  const wsPosix = resolveWorkspacePath(toPosixPath(deps.homeDir), cfg.workspace ?? "", v.target);
+  const headers = { "x-codehost-workspace": wsPosix };
+
+  const cmd = findSetupScript(deps.homeDir);
+  if (!cmd) return json(200, { workspace: wsPosix }, headers); // no script: hand back the path
+
+  const lockKey = fromPosixPath(wsPosix);
+  const existing = inFlight.get(lockKey);
+  const body = existing
+    ? coalescedBody(existing) // a provision is already running for this workspace
+    : freshBody(cmd, deps, v.target, host, lockKey);
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store", ...headers },
+  });
+}
+
+/** Spawn the setup script, streaming merged stdout+stderr, ending with an exit
+ *  sentinel the browser parses for success/failure. */
+function freshBody(
+  cmd: string[],
+  deps: ProvisionDeps,
+  target: ProvisionTarget,
+  host: string,
+  lockKey: string,
+): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      let resolveDone!: (code: number) => void;
+      inFlight.set(lockKey, new Promise<number>((r) => (resolveDone = r)));
+      const say = (s: string) => controller.enqueue(enc.encode(s));
+      say(`[codehost] provisioning ${host}/${target.owner}/${target.repo}@${target.branch}\n`);
+      let code = 1;
+      try {
+        const proc = Bun.spawn(cmd, {
+          cwd: deps.homeDir,
+          env: {
+            ...process.env,
+            CODEHOST_OWNER: target.owner,
+            CODEHOST_REPO: target.repo,
+            CODEHOST_BRANCH: target.branch,
+            CODEHOST_HOST: host,
+            CODEHOST_HOME: deps.homeDir,
+            CODEHOST_WS: fromPosixPath(lockKey),
+          },
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+        const timer = setTimeout(() => {
+          try {
+            proc.kill();
+          } catch {
+            // already gone
+          }
+        }, TIMEOUT_MS);
+        const pump = async (stream: ReadableStream<Uint8Array>) => {
+          const reader = stream.getReader();
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            controller.enqueue(value);
+          }
+        };
+        await Promise.all([pump(proc.stdout), pump(proc.stderr)]);
+        code = await proc.exited;
+        clearTimeout(timer);
+      } catch (err) {
+        say(`[codehost] provision error: ${String(err)}\n`);
+      } finally {
+        inFlight.delete(lockKey);
+        resolveDone(code);
+        say(`\n::codehost:exit=${code}\n`);
+        controller.close();
+      }
+    },
+  });
+}
+
+/** Attach to a running provision: wait for it, then emit the exit sentinel. */
+function coalescedBody(existing: Promise<number>): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      controller.enqueue(enc.encode("[codehost] provision already running for this workspace; waiting…\n"));
+      const code = await existing.catch(() => 1);
+      controller.enqueue(enc.encode(`\n::codehost:exit=${code}\n`));
+      controller.close();
+    },
+  });
+}
+
+function json(status: number, obj: unknown, extra: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(obj), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store", ...extra },
+  });
+}

package/src/cli/run-server.ts

@@ -2,6 +2,7 @@ import { type PeerMeta, newPeerId } from "../shared/signaling";
 import { SignalingClient } from "../shared/signaling-client";
 import { RtcDaemon } from "./rtc-daemon";
 import { Tunnel } from "./tunnel";
+import { handleProvision, type ProvisionDeps } from "./provision-server";
 
 export interface LaunchResult {
   /** Local port to tunnel to. */
@@ -24,6 +25,9 @@ export interface RunServerOptions {
   label: string;
   /** Prepare the local target to tunnel, given the /vs/<peerId> base path. */
   launch: (basePath: string) => Promise<LaunchResult>;
+  /** Enables `/__codehost/provision` on the tunnel (serve only — runs the home's
+   *  setup.sh). Omitted by `expose`, which has no home/workspace. */
+  provision?: ProvisionDeps;
 }
 
 /**
@@ -64,7 +68,12 @@ export async function runServer(opts: RunServerOptions): Promise<never> {
     sendSignal: (to, data) => client.sendSignal(to, data),
     onChannel: (viewerId, channel) => {
       console.log(`[codehost] viewer ${viewerId.slice(0, 8)} connected; bridging to :${target.port}`);
-      new Tunnel(channel, target.port, target.stripBasePath);
+      new Tunnel(
+        channel,
+        target.port,
+        target.stripBasePath,
+        opts.provision ? (rawPath) => handleProvision(rawPath, opts.provision!) : undefined,
+      );
     },
   });
 

package/src/cli/tunnel.ts

@@ -1,4 +1,5 @@
 import type { DataChannel } from "node-datachannel";
+import { isProvisionPath } from "./provision-server";
 import {
   type HttpReqHead,
   Op,
@@ -54,6 +55,9 @@ export class Tunnel {
      * doesn't know it, so we strip `/vs/<peerId>` before proxying.
      */
     private stripPrefix?: string,
+    /** Handles `/__codehost/*` requests locally (provisioning) instead of
+     *  forwarding to the local server. Wired only for `serve` (not `expose`). */
+    private onProvision?: (rawPath: string) => Promise<Response>,
   ) {
     this.origin = `http://127.0.0.1:${vscodePort}`;
     this.wsOrigin = `ws://127.0.0.1:${vscodePort}`;
@@ -134,12 +138,15 @@ export class Tunnel {
     const body = hasBody ? concat(stream.body) : undefined;
 
     try {
-      const res = await fetch(this.origin + this.localPath(path), {
-        method,
-        headers: reqHeaders,
-        body: body as BodyInit | undefined,
-        redirect: "manual",
-      });
+      const res =
+        this.onProvision && isProvisionPath(path)
+          ? await this.onProvision(path)
+          : await fetch(this.origin + this.localPath(path), {
+              method,
+              headers: reqHeaders,
+              body: body as BodyInit | undefined,
+              redirect: "manual",
+            });
 
       const resHeaders: Record<string, string> = {};
       res.headers.forEach((v, k) => {

package/src/shared/provision.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import { repoAllowed, resolveWorkspacePath, validateProvisionTarget } from "./provision";
+
+describe("validateProvisionTarget — the injection boundary", () => {
+  test("accepts normal identities", () => {
+    const r = validateProvisionTarget("snomiao", "codehost", "main");
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.target).toEqual({ owner: "snomiao", repo: "codehost", branch: "main" });
+  });
+
+  test("accepts branch with slashes and hyphens", () => {
+    const r = validateProvisionTarget("snomiao", "codehost", "feat/some-thing");
+    expect(r.ok).toBe(true);
+  });
+
+  test("empty branch defaults to main", () => {
+    const r = validateProvisionTarget("snomiao", "codehost", "");
+    expect(r.ok && r.target.branch).toBe("main");
+  });
+
+  // The whole point: these must NOT pass.
+  test("rejects path traversal in owner/repo", () => {
+    expect(validateProvisionTarget("..", "codehost", "main").ok).toBe(false);
+    expect(validateProvisionTarget(".", "codehost", "main").ok).toBe(false);
+    expect(validateProvisionTarget("snomiao", "..", "main").ok).toBe(false);
+    expect(validateProvisionTarget("a/b", "codehost", "main").ok).toBe(false); // slash
+    expect(validateProvisionTarget(".ssh", "codehost", "main").ok).toBe(false); // leading dot
+  });
+
+  test("rejects traversal / leading-dash / junk in branch", () => {
+    expect(validateProvisionTarget("o", "r", "a/../../etc").ok).toBe(false);
+    expect(validateProvisionTarget("o", "r", "..").ok).toBe(false);
+    expect(validateProvisionTarget("o", "r", "-x").ok).toBe(false); // option injection
+    expect(validateProvisionTarget("o", "r", "feat/-x").ok).toBe(false);
+    expect(validateProvisionTarget("o", "r", "a b").ok).toBe(false); // whitespace
+    expect(validateProvisionTarget("o", "r", "a;rm -rf").ok).toBe(false); // shell meta
+    expect(validateProvisionTarget("o", "r", "a$(id)").ok).toBe(false);
+    expect(validateProvisionTarget("o", "r", "a`id`").ok).toBe(false);
+  });
+});
+
+describe("resolveWorkspacePath — daemon-authoritative, cannot escape home", () => {
+  test("fills the default layout under home", () => {
+    const t = { owner: "snomiao", repo: "codehost", branch: "main" };
+    expect(resolveWorkspacePath("/Users/sno/ws", "", t)).toBe("/Users/sno/ws/snomiao/codehost/tree/main");
+  });
+
+  test("honors a custom layout template (e.g. config.yaml ws/ home model)", () => {
+    const t = { owner: "snomiao", repo: "codehost", branch: "feat/x" };
+    expect(resolveWorkspacePath("/home/me", "ws/{owner}/{repo}/tree/{branch}", t)).toBe(
+      "/home/me/ws/snomiao/codehost/tree/feat/x",
+    );
+  });
+
+  test("a validated target can never produce a path above home", () => {
+    // Only validated targets reach here; confirm the segments are inert.
+    const v = validateProvisionTarget("snomiao", "codehost", "main");
+    expect(v.ok).toBe(true);
+    if (v.ok) {
+      const p = resolveWorkspacePath("/Users/sno/ws", "{owner}/{repo}/tree/{branch}", v.target);
+      expect(p.startsWith("/Users/sno/ws/")).toBe(true);
+      expect(p.includes("/../")).toBe(false);
+    }
+  });
+});
+
+describe("repoAllowed", () => {
+  test("empty/absent allowlist allows all", () => {
+    expect(repoAllowed("github.com/x/y", undefined)).toBe(true);
+    expect(repoAllowed("github.com/x/y", [])).toBe(true);
+  });
+
+  test("exact + owner wildcard", () => {
+    expect(repoAllowed("github.com/snomiao/codehost", ["github.com/snomiao/codehost"])).toBe(true);
+    expect(repoAllowed("github.com/snomiao/codehost", ["github.com/snomiao/*"])).toBe(true);
+    expect(repoAllowed("github.com/evil/repo", ["github.com/snomiao/*"])).toBe(false);
+    expect(repoAllowed("gitlab.com/snomiao/x", ["github.com/snomiao/*"])).toBe(false);
+  });
+});

package/src/shared/provision.ts

@@ -0,0 +1,67 @@
+// Pure provisioning helpers: the security boundary for "open a repo link runs a
+// host setup script". The room token already grants code execution (the editor
+// is a terminal), so script execution is not new trust — the only new surface is
+// a crafted/shared link auto-triggering setup.sh with attacker-chosen
+// owner/repo/branch. That surface is bounded entirely here: validate the
+// identity so it can't traverse out of the home root or inject options, and
+// compute the workspace path **daemon-authoritatively** (never from script
+// output). Kept pure + unit-tested precisely because it's the injection gate.
+
+import { DEFAULT_BRANCH, DEFAULT_LAYOUT } from "./repo";
+
+export interface ProvisionTarget {
+  owner: string;
+  repo: string;
+  branch: string;
+}
+
+export type ValidateResult = { ok: true; target: ProvisionTarget } | { ok: false; reason: string };
+
+// First char must be alphanumeric: rejects "..", ".", leading-dot tricks, and a
+// leading "-" in one stroke (a bare `[A-Za-z0-9._-]+` would match "..").
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+// Positive allowlist for a branch ref as a whole: safe path chars only. Excludes
+// whitespace, control chars, and shell metacharacters by construction.
+const BRANCH_CHARS = /^[A-Za-z0-9._/-]+$/;
+
+/** Validate the (owner, repo, branch) identity carried by a repo deep link before
+ *  it is used to build a filesystem path or passed to a setup script. Branch may
+ *  contain "/" (worktree refs) but no empty/`.`/`..` segment and no segment
+ *  starting with "-" (else `git checkout "$BRANCH"` eats it as an option flag —
+ *  option injection survives env-passing because the script interpolates it). An
+ *  empty branch defaults to DEFAULT_BRANCH. */
+export function validateProvisionTarget(owner: string, repo: string, branch: string): ValidateResult {
+  if (!SEGMENT.test(owner)) return { ok: false, reason: `invalid owner: ${owner}` };
+  if (!SEGMENT.test(repo)) return { ok: false, reason: `invalid repo: ${repo}` };
+  const b = (branch || DEFAULT_BRANCH).trim();
+  if (!BRANCH_CHARS.test(b)) return { ok: false, reason: `invalid branch: ${b}` };
+  const segs = b.split("/");
+  if (segs.some((s) => s === "" || s === "." || s === ".." || s.startsWith("-"))) {
+    return { ok: false, reason: `invalid branch: ${b}` };
+  }
+  return { ok: true, target: { owner, repo, branch: b } };
+}
+
+/** Fill a workspace layout template from a *validated* target. POSIX-space (the
+ *  served cwd is already `toPosixPath`'d), so the result is the `?folder=` form.
+ *  Safe against traversal only because `target` passed validateProvisionTarget. */
+export function resolveWorkspacePath(homePosix: string, layout: string, target: ProvisionTarget): string {
+  const rel = (layout || DEFAULT_LAYOUT)
+    .replace(/\{owner\}/g, target.owner)
+    .replace(/\{repo\}/g, target.repo)
+    .replace(/\{branch\}/g, target.branch);
+  return `${homePosix.replace(/\/+$/, "")}/${rel.replace(/^\/+/, "")}`;
+}
+
+/** Whether a repo may be auto-provisioned. An empty/absent allowlist allows all
+ *  (provisioning is already opt-in by the presence of setup.sh); otherwise the
+ *  repo key `<host>/<owner>/<repo>` must match an entry, where a trailing `/*`
+ *  is an owner/prefix wildcard (e.g. `github.com/snomiao/*`). */
+export function repoAllowed(repoKey: string, allowlist: string[] | undefined): boolean {
+  if (!allowlist || allowlist.length === 0) return true;
+  return allowlist.some((rule) => {
+    const r = rule.trim();
+    if (r.endsWith("/*")) return repoKey.startsWith(r.slice(0, -1));
+    return repoKey === r;
+  });
+}

package/src/shared/repo.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { parseDeepLink, pickRoomMatch, repoKey, resolveDevTarget, shareableDeepLink, toPosixPath } from "./repo";
+import { gitUrlToPath, parseDeepLink, pickRoomMatch, repoKey, resolveDevTarget, resolveRepoTarget, shareableDeepLink, toPosixPath } from "./repo";
 import type { PeerInfo } from "./signaling";
 import { parseGitRemote } from "../cli/git";
 
@@ -194,6 +194,53 @@ describe("shareableDeepLink", () => {
   });
 });
 
+describe("resolveRepoTarget root selection", () => {
+  const root = (peerId: string, cwd: string): PeerInfo => ({
+    peerId,
+    role: "server",
+    meta: { name: peerId, host: "Mac", cwd, kind: "root" },
+  });
+
+  test("among nested roots, picks the deepest (longest cwd)", () => {
+    const servers = [root("shallow", "/Users/sno"), root("deep", "/Users/sno/ws")];
+    const res = resolveRepoTarget(servers, { host: "github.com", owner: "snomiao", name: "codehost" });
+    expect(res?.peerId).toBe("deep");
+    expect(res?.folder).toBe("/Users/sno/ws/snomiao/codehost/tree/main");
+  });
+
+  test("an exact repo daemon still wins over any root", () => {
+    const servers: PeerInfo[] = [
+      root("deep", "/Users/sno/ws"),
+      { peerId: "exact", role: "server", meta: { name: "x", host: "Mac", cwd: "/x", repo: "github.com/snomiao/codehost" } },
+    ];
+    expect(resolveRepoTarget(servers, { host: "github.com", owner: "snomiao", name: "codehost" })?.peerId).toBe("exact");
+  });
+});
+
+describe("gitUrlToPath", () => {
+  test("github URLs -> /gh, preserving branch (incl. slashes)", () => {
+    expect(gitUrlToPath("https://github.com/snomiao/codehost")).toBe("/gh/snomiao/codehost");
+    expect(gitUrlToPath("https://github.com/snomiao/codehost/tree/main")).toBe("/gh/snomiao/codehost/tree/main");
+    expect(gitUrlToPath("github.com/snomiao/codehost")).toBe("/gh/snomiao/codehost");
+    expect(gitUrlToPath("https://github.com/snomiao/codehost.git")).toBe("/gh/snomiao/codehost");
+    expect(gitUrlToPath("https://github.com/snomiao/codehost/tree/feat/x")).toBe("/gh/snomiao/codehost/tree/feat/x");
+    expect(gitUrlToPath("https://github.com/snomiao/codehost/")).toBe("/gh/snomiao/codehost");
+    expect(gitUrlToPath("https://github.com/snomiao/codehost?tab=readme#x")).toBe("/gh/snomiao/codehost");
+  });
+
+  test("other hosts + scp form -> /git/<host>/...", () => {
+    expect(gitUrlToPath("https://gitlab.com/group/proj/tree/dev")).toBe("/git/gitlab.com/group/proj/tree/dev");
+    expect(gitUrlToPath("git@github.com:snomiao/codehost.git")).toBe("/gh/snomiao/codehost");
+  });
+
+  test("non-repo / junk -> null", () => {
+    expect(gitUrlToPath("")).toBeNull();
+    expect(gitUrlToPath("not a url")).toBeNull();
+    expect(gitUrlToPath("https://github.com/snomiao")).toBeNull(); // no repo
+    expect(gitUrlToPath("/gh/snomiao/codehost")).toBeNull(); // already a deep link, no host
+  });
+});
+
 describe("pickRoomMatch (cross-room ranking)", () => {
   const exact = { token: "tA", resolution: { peerId: "p1" } }; // no folder = exact
   const root = { token: "tB", resolution: { peerId: "p2", folder: "/work/me/repo" } };

package/src/shared/repo.ts

@@ -100,6 +100,16 @@ export function toPosixPath(p: string): string {
   return p.replace(/\\/g, "/");
 }
 
+/** Inverse of `toPosixPath` for the host OS: the VS Code `?folder=` form back to
+ *  a real filesystem path. `/C:/ws` -> `C:\ws` (Windows); a POSIX path is
+ *  returned unchanged (only Windows cwds carry the `/<drive>:/` shape). */
+export function fromPosixPath(p: string): string {
+  const drive = /^\/([A-Za-z]):(\/.*)?$/.exec(p);
+  if (!drive) return p;
+  const rest = (drive[2] ?? "").replace(/\//g, "\\");
+  return `${drive[1]}:${rest || "\\"}`;
+}
+
 /** Fill a layout template from a repo target (default branch -> DEFAULT_BRANCH). */
 export function fillLayout(layout: string, t: RepoTarget): string {
   return layout
@@ -137,6 +147,28 @@ export function shareableDeepLink(opts: {
   return null;
 }
 
+/**
+ * Turn a pasted git repo URL into a codehost deep-link path: github.com ->
+ * `/gh/<owner>/<repo>`, any other host -> `/git/<host>/<owner>/<repo>`,
+ * preserving `/tree/<branch>`. Accepts with or without a scheme, an `scp`-style
+ * `git@host:owner/repo`, a trailing `.git`, query/hash, and a branch containing
+ * slashes. Returns null when it isn't a recognizable repo URL — lets the "open a
+ * GitHub URL" box reuse the same resolution as a typed deep link.
+ */
+export function gitUrlToPath(input: string): string | null {
+  let s = input.trim();
+  if (!s) return null;
+  s = s.replace(/^[a-z][a-z0-9+.-]*:\/\//i, ""); // scheme://
+  s = s.replace(/^[^@/]+@/, ""); // user@ (incl. git@)
+  s = s.replace(/^([^/:]+):(?!\d)/, "$1/"); // scp-style host:owner/repo -> host/owner/repo
+  s = s.split(/[?#]/)[0].replace(/\/+$/, ""); // drop query/hash + trailing slash
+  const m = s.match(/^([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?(?:\/tree\/(.+))?$/);
+  if (!m) return null;
+  const host = m[1].toLowerCase();
+  if (!host.includes(".")) return null; // require a real hostname (github.com)
+  return shareableDeepLink({ repo: `${host}/${m[2]}/${m[3]}`, branch: m[4] });
+}
+
 export interface Resolution {
   peerId: string;
   /** Folder to open via ?folder= (root kind); undefined opens the repo as-is. */
@@ -146,7 +178,10 @@ export interface Resolution {
 /**
  * Pick the best live server for a repo deep link. Prefers an exact `repo`
  * daemon; otherwise falls back to a `root` daemon that can open the subfolder.
- * Returns null if nothing matches.
+ * Among several roots, prefers the **deepest** (longest cwd) — with a nested
+ * setup like /Users/sno and /Users/sno/ws both serving, the layout subfolder
+ * exists under the deeper one (observed: /gh/snomiao/codehost belongs to
+ * /Users/sno/ws/..., not /Users/sno/...). Returns null if nothing matches.
  */
 export function resolveRepoTarget(servers: PeerInfo[], target: RepoTarget): Resolution | null {
   const key = repoKey(target);
@@ -155,7 +190,9 @@ export function resolveRepoTarget(servers: PeerInfo[], target: RepoTarget): Reso
   );
   if (repoMatch) return { peerId: repoMatch.peerId };
 
-  const root = servers.find((s) => s.meta?.kind === "root");
+  const root = servers
+    .filter((s) => s.meta?.kind === "root")
+    .sort((a, b) => (b.meta?.cwd.length ?? 0) - (a.meta?.cwd.length ?? 0))[0];
   if (root && root.meta) {
     const folder = `${trimSlash(root.meta.cwd)}/${fillLayout(root.meta.layout || DEFAULT_LAYOUT, target)}`;
     return { peerId: root.peerId, folder };

package/src/web/discovery.tsx

@@ -10,7 +10,9 @@ import { connBroker } from "./conn-broker";
 import {
   DEFAULT_BRANCH,
   type DeepLink,
+  type RepoTarget,
   type RoomMatch,
+  gitUrlToPath,
   parseDeepLink,
   pickRoomMatch,
   repoKey,
@@ -23,7 +25,7 @@ import { deriveTags, matchQuery, shortRoomLabel, tagKey } from "../shared/tags";
 
 const TOKEN_KEY = "codehost.token";
 
-type ConnState = "idle" | "connecting" | "connected" | "failed";
+type ConnState = "idle" | "connecting" | "provisioning" | "connected" | "failed";
 
 /** A server discovered in a specific room (its token routes the signaling). */
 type RoomedServer = { server: PeerInfo; room: string };
@@ -162,6 +164,12 @@ export function Discovery() {
   const [editingToken, setEditingToken] = useState(false);
   const [tokenError, setTokenError] = useState<string | null>(null);
 
+  // "Open a GitHub repo" box: paste a github.com URL -> navigate to its /gh/
+  // deep link, which resolves/opens (and, once provisioning lands, materializes)
+  // the workspace.
+  const [ghUrl, setGhUrl] = useState("");
+  const [ghError, setGhError] = useState<string | null>(null);
+
   // Fake-tag filter over the merged workspace list: a free-text box plus a set
   // of pinned tag tokens (chips). Both feed the same `ay ls`-style AND matcher.
   const [filter, setFilter] = useState("");
@@ -173,6 +181,8 @@ export function Discovery() {
   const [activePeerId, setActivePeerId] = useState<string | null>(null);
   const [connState, setConnState] = useState<ConnState>("idle");
   const [iframeSrc, setIframeSrc] = useState<string | null>(null);
+  // Streamed setup.sh output shown while connState === "provisioning".
+  const [provisionLog, setProvisionLog] = useState("");
 
   const rtcRef = useRef<RtcClient | null>(null);
   const activePeerRef = useRef<string | null>(null);
@@ -312,6 +322,22 @@ export function Discovery() {
     setEditingToken(false);
   }
 
+  function openGithubUrl(e: React.FormEvent) {
+    e.preventDefault();
+    const path = gitUrlToPath(ghUrl);
+    if (!path) {
+      setGhError("not a recognizable git repo URL");
+      return;
+    }
+    setGhError(null);
+    setGhUrl("");
+    // Navigate to the deep link and reconcile: connect if a daemon already
+    // serves it (provisioning, later, will materialize it when it doesn't).
+    history.pushState(null, "", path);
+    setResolving(deepLinkLabel(parseDeepLink(path)));
+    syncToUrl();
+  }
+
   function leaveRoom(t: string) {
     if (activeRoomRef.current === t) disconnect();
     setTokens((prev) => prev.filter((x) => x !== t));
@@ -328,7 +354,13 @@ export function Discovery() {
     sendersRef.current.delete(t);
   }
 
-  async function connectTo(server: PeerInfo, room: string, folder?: string, fromHistory = false) {
+  async function connectTo(
+    server: PeerInfo,
+    room: string,
+    folder?: string,
+    fromHistory = false,
+    repoTarget?: RepoTarget,
+  ) {
     const send = sendersRef.current.get(room);
     if (!send) return;
     dialingRef.current = true; // synchronous gate against concurrent triggers
@@ -351,7 +383,7 @@ export function Discovery() {
       // handshake) and push a history entry, so Back returns to the list and
       // Forward returns here. When `fromHistory`, the browser already set the URL
       // (back/forward/reconnect) — don't push again, but a prior entry exists.
-      const openFolder = folder ?? server.meta?.cwd;
+      let openFolder = folder ?? server.meta?.cwd;
       if (fromHistory) {
         pushedRef.current = true;
         sharePathRef.current = window.location.pathname;
@@ -402,10 +434,23 @@ export function Discovery() {
         });
 
       await connBroker.connect(server.peerId, establish);
+
+      // For a repo deep link, ask the daemon to provision (run .codehost/setup.sh
+      // and hand back the authoritative workspace path) before opening. Streams
+      // the log under the "provisioning" state. Daemons without the route (older
+      // builds) return no path → fall back to the browser-computed folder.
+      if (repoTarget) {
+        setConnState("provisioning");
+        setProvisionLog("");
+        const ws = await runProvision(server.peerId, repoTarget);
+        if (activePeerRef.current !== server.peerId) return; // cancelled/switched mid-provision
+        if (ws) openFolder = ws;
+      }
+
       setConnState("connected");
       // The daemon no longer sets a default folder (current VS Code serve-web
       // dropped that flag), so open the served workspace from here: the
-      // deep-link folder if we have one, else the server's reported cwd.
+      // provisioned/deep-link folder if we have one, else the server's reported cwd.
       activeFolderRef.current = openFolder;
       setIframeSrc(`/vs/${server.peerId}/${folderQuery(openFolder)}`);
       setResolving(null);
@@ -423,6 +468,48 @@ export function Discovery() {
     }
   }
 
+  // Ask the daemon to provision a repo workspace over the tunnel: stream
+  // setup.sh's output into `provisionLog` and return the daemon-authoritative
+  // path (the `x-codehost-workspace` header). Returns null when the daemon has
+  // no provision route (older build) or the call fails — caller falls back.
+  async function runProvision(peerId: string, t: RepoTarget): Promise<string | null> {
+    const params = new URLSearchParams({
+      owner: t.owner,
+      repo: t.name,
+      branch: t.branch ?? DEFAULT_BRANCH,
+      host: t.host,
+    });
+    let res: Response;
+    try {
+      res = await connBroker.tunnelFor(peerId).fetch("GET", `/__codehost/provision?${params}`, {});
+    } catch {
+      return null;
+    }
+    const ws = res.headers.get("x-codehost-workspace");
+    if (!ws) {
+      await res.body?.cancel().catch(() => {});
+      return null;
+    }
+    let buf = `[codehost] provisioning ${t.owner}/${t.name}@${t.branch ?? DEFAULT_BRANCH}…\n`;
+    setProvisionLog(buf);
+    if (res.body) {
+      const reader = res.body.getReader();
+      const dec = new TextDecoder();
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buf += dec.decode(value, { stream: true });
+          // Hide the internal exit sentinel from the displayed log.
+          setProvisionLog(buf.replace(/\n::codehost:exit=\d+\n?/, "\n"));
+        }
+      } catch {
+        // stream interrupted (channel closed) — return the path anyway
+      }
+    }
+    return ws;
+  }
+
   // Shareable deep-link pathname for a server+folder, with no side effects (no
   // token — Share adds that). Keeps an existing deep-link path as-is; otherwise
   // derives /gh|/git|/dev from the server's repo identity or opened folder.
@@ -470,7 +557,7 @@ export function Discovery() {
       const match = allServers.find((x) => x.server.peerId === res.peerId);
       if (!match) return;
       resolvedRef.current = true;
-      void connectTo(match.server, match.room, res.folder);
+      void connectTo(match.server, match.room, res.folder, false, dl.type === "repo" ? dl.target : undefined);
       return;
     }
     // No deep link, but a token arrived via the URL: open that room's server
@@ -540,7 +627,7 @@ export function Discovery() {
     const target = findServerForDeepLink(dl);
     if (!target) return; // its server isn't present (yet) — wait for it to appear
     if (activePeerRef.current === target.server.peerId && connStateRef.current === "connected") return;
-    void connectTo(target.server, target.room, target.folder, true);
+    void connectTo(target.server, target.room, target.folder, true, dl.type === "repo" ? dl.target : undefined);
   }
 
   function disconnect() {
@@ -607,6 +694,27 @@ export function Discovery() {
     />
   ));
 
+  // Provisioning view: the daemon's setup.sh is running; stream its log.
+  if (connState === "provisioning") {
+    return (
+      <>
+        {roomClients}
+        <div style={styles.page}>
+          <header style={styles.header}>
+            <span style={styles.brand}>codehost</span>
+            <span style={styles.dim}>·</span>
+            <span style={styles.dim}>provisioning…</span>
+            <span style={{ flex: 1 }} />
+            <button style={styles.connectBtn} onClick={disconnect}>
+              Cancel
+            </button>
+          </header>
+          <pre style={styles.provLog}>{provisionLog || "starting…"}</pre>
+        </div>
+      </>
+    );
+  }
+
   // Connected view: VS Code in an iframe, served over the tunnel.
   if (iframeSrc && connState === "connected") {
     return (
@@ -735,6 +843,26 @@ export function Discovery() {
             </>
           )}
 
+          {tokens.length > 0 && (
+            <>
+              <form onSubmit={openGithubUrl} style={styles.ghForm}>
+                <input
+                  value={ghUrl}
+                  onChange={(e) => {
+                    setGhUrl(e.target.value);
+                    if (ghError) setGhError(null);
+                  }}
+                  placeholder="open a repo…  paste a github.com URL"
+                  style={styles.input}
+                />
+                <button type="submit" style={styles.button}>
+                  Open
+                </button>
+              </form>
+              {ghError && <p style={styles.tokenError}>{ghError}</p>}
+            </>
+          )}
+
           <div style={styles.listHead}>
             <h2 style={styles.h2}>Workspaces</h2>
             {serverCount > 0 && (
@@ -836,6 +964,7 @@ const styles: Record<string, React.CSSProperties> = {
   roomChipX: { background: "transparent", border: "none", color: "inherit", cursor: "pointer", fontSize: 11, padding: 0, lineHeight: 1 },
   input: { flex: 1, background: "#252525", border: "1px solid #3d3d3d", color: "#eee", padding: "8px 10px", borderRadius: 6, fontSize: 13, outline: "none" },
   button: { background: "#0e639c", border: "none", color: "#fff", padding: "8px 16px", borderRadius: 6, cursor: "pointer", fontSize: 13 },
+  ghForm: { display: "flex", alignItems: "center", gap: 8, margin: "0 0 14px" },
   listHead: { display: "flex", alignItems: "baseline", gap: 10, margin: "0 0 12px" },
   h2: { fontSize: 14, color: "#aaa", fontWeight: 600, margin: 0 },
   count: { fontSize: 12, color: "#888", fontFamily: "monospace" },
@@ -866,4 +995,5 @@ const styles: Record<string, React.CSSProperties> = {
   echo: { marginTop: 6, fontSize: 12, color: "#4ec9b0", fontFamily: "monospace" },
   connectBtn: { background: "#0e639c", border: "none", color: "#fff", padding: "6px 14px", borderRadius: 6, cursor: "pointer", fontSize: 13 },
   shareBtn: { background: "transparent", border: "1px solid #3d3d3d", color: "#ccc", padding: "6px 14px", borderRadius: 6, cursor: "pointer", fontSize: 13 },
+  provLog: { flex: 1, margin: 0, padding: "14px 18px", overflow: "auto", background: "#1e1e1e", color: "#ccc", fontFamily: "monospace", fontSize: 12.5, lineHeight: 1.5, whiteSpace: "pre-wrap" },
 };