viagen 0.0.10 → 0.0.12

package/README.md

@@ -1,6 +1,6 @@
 # viagen
 
-A dev server plugin (Vite, webpack, Next.js) and CLI tool that enables you to use Claude Code in a sandbox — instantly.
+A Vite dev server plugin and CLI tool that enables you to use Claude Code in a sandbox — instantly.
 
 ## Prerequisites
 
@@ -14,8 +14,6 @@ A dev server plugin (Vite, webpack, Next.js) and CLI tool that enables you to us
 npm install --save-dev viagen
 ```
 
-### Vite
-
 ```ts
 // vite.config.ts
 import { defineConfig } from 'vite'
@@ -26,66 +24,6 @@ export default defineConfig({
 })
 ```
 
-### webpack
-
-```js
-// webpack.config.js
-const { setupViagen } = require('viagen/webpack')
-
-module.exports = {
-  devServer: {
-    setupMiddlewares: (middlewares, devServer) => {
-      setupViagen(devServer)
-      return middlewares
-    }
-  }
-}
-```
-
-### Next.js
-
-Next.js uses its own dev server, so viagen runs via a custom server file.
-
-```bash
-npm install --save-dev viagen connect
-```
-
-```ts
-// server.ts
-import http from 'node:http'
-import next from 'next'
-import connect from 'connect'
-import { setupViagen } from 'viagen/webpack'
-
-const dev = process.env.NODE_ENV !== 'production'
-const app = next({ dev, hostname: 'localhost', port: 3000 })
-const handle = app.getRequestHandler()
-
-app.prepare().then(() => {
-  const server = connect()
-
-  setupViagen({
-    app: server,
-    compiler: { hooks: { done: { tap: () => {} } } },
-  })
-
-  server.use((req, res) => handle(req, res))
-  http.createServer(server).listen(3000, () => {
-    console.log('> Ready on http://localhost:3000')
-  })
-})
-```
-
-Then update your dev script:
-
-```json
-{
-  "scripts": {
-    "dev": "npx tsx server.ts"
-  }
-}
-```
-
 ## Step 2 — Setup
 
 ```bash
@@ -115,7 +53,7 @@ npx viagen sandbox --timeout 60
 npx viagen sandbox stop <sandboxId>
 ```
 
-## Vite Plugin Options
+## Plugin Options
 
 ```ts
 viagen({
@@ -136,8 +74,17 @@ help build and modify the app. Files you edit will trigger Vite HMR
 automatically. You can read .viagen/server.log to check recent Vite dev server
 output (compile errors, HMR updates, warnings). When running in a sandbox with
 git, the gh CLI is available and authenticated — you can create pull requests,
-comment on issues, and manage releases. If Vercel credentials are set, you can
-run "vercel deploy" to publish a preview and share the URL. Be concise.
+comment on issues, and manage releases.
+
+Publishing workflow:
+- If you are on a feature branch (not main/master): commit your changes, push
+  to the remote, and create a pull request using "gh pr create". Share the PR URL.
+- If you are on main/master and Vercel credentials are set ($VERCEL_TOKEN):
+  commit, push, and run "vercel deploy" to publish a preview. Share the preview URL.
+- Check your current branch with "git branch --show-current" before deciding
+  which workflow to use.
+
+Be concise.
 ```
 
 Recent build errors are automatically appended to give Claude context about what went wrong. To customize the prompt, you can replace it entirely or extend the default:
@@ -154,18 +101,6 @@ viagen({
 })
 ```
 
-## webpack Options
-
-```js
-setupViagen(devServer, {
-  position: 'bottom-right',  // toggle button position
-  model: 'sonnet',           // claude model
-  panelWidth: 420,           // chat panel width in px
-  ui: true,                  // inject chat panel into pages
-  systemPrompt: '...',       // custom system prompt
-})
-```
-
 ## API
 
 Every viagen endpoint is available as an API. Build your own UI, integrate with CI, or script Claude from the command line.

package/dist/cli.js

@@ -48,20 +48,39 @@ async function deploySandbox(opts) {
   const token = randomUUID();
   const useGit = !!opts.git;
   const timeoutMs = (opts.timeoutMinutes ?? 30) * 60 * 1e3;
-  const sandbox2 = await Sandbox.create({
-    runtime: "node22",
-    ports: [5173],
-    timeout: timeoutMs,
-    ...opts.git ? {
-      source: {
-        type: "git",
-        url: opts.git.remoteUrl,
-        username: "x-access-token",
-        password: opts.git.token,
-        revision: opts.git.branch
-      }
-    } : {}
-  });
+  const sourceOpts = opts.git ? {
+    source: {
+      type: "git",
+      url: opts.git.remoteUrl,
+      username: "x-access-token",
+      password: opts.git.token,
+      ...opts.git.revision ? { revision: opts.git.revision } : {}
+    }
+  } : {};
+  let sandbox2;
+  try {
+    sandbox2 = await Sandbox.create({
+      runtime: "node22",
+      ports: [5173],
+      timeout: timeoutMs,
+      ...sourceOpts
+    });
+  } catch (err) {
+    console.error("\nSandbox creation failed.");
+    if (opts.git) {
+      console.error(`  URL:      ${opts.git.remoteUrl}`);
+      console.error(`  Revision: ${opts.git.revision ?? "(default branch)"}`);
+      console.error(`  Branch:   ${opts.git.branch}`);
+    }
+    const apiErr = err;
+    if (apiErr.message) console.error(`  Message:  ${apiErr.message}`);
+    if (apiErr.json) {
+      console.error(`  Response: ${JSON.stringify(apiErr.json, null, 2)}`);
+    } else if (apiErr.text) {
+      console.error(`  Response: ${apiErr.text}`);
+    }
+    throw err;
+  }
   try {
     if (useGit && opts.git) {
       await sandbox2.runCommand("git", [
@@ -108,26 +127,27 @@ async function deploySandbox(opts) {
         await sandbox2.writeFiles(files);
       }
     }
-    const envLines = [
-      `VIAGEN_AUTH_TOKEN=${token}`,
-      `VIAGEN_SESSION_START=${Math.floor(Date.now() / 1e3)}`,
-      `VIAGEN_SESSION_TIMEOUT=${(opts.timeoutMinutes ?? 30) * 60}`
-    ];
+    const envMap = { ...opts.envVars ?? {} };
+    envMap["VIAGEN_AUTH_TOKEN"] = token;
+    envMap["VIAGEN_SESSION_START"] = String(Math.floor(Date.now() / 1e3));
+    envMap["VIAGEN_SESSION_TIMEOUT"] = String((opts.timeoutMinutes ?? 30) * 60);
     if (opts.apiKey) {
-      envLines.push(`ANTHROPIC_API_KEY=${opts.apiKey}`);
+      envMap["ANTHROPIC_API_KEY"] = opts.apiKey;
     } else if (opts.oauth) {
-      envLines.push(`CLAUDE_ACCESS_TOKEN=${opts.oauth.accessToken}`);
-      envLines.push(`CLAUDE_REFRESH_TOKEN=${opts.oauth.refreshToken}`);
-      envLines.push(`CLAUDE_TOKEN_EXPIRES=${opts.oauth.tokenExpires}`);
+      envMap["CLAUDE_ACCESS_TOKEN"] = opts.oauth.accessToken;
+      envMap["CLAUDE_REFRESH_TOKEN"] = opts.oauth.refreshToken;
+      envMap["CLAUDE_TOKEN_EXPIRES"] = opts.oauth.tokenExpires;
     }
     if (opts.git) {
-      envLines.push(`GITHUB_TOKEN=${opts.git.token}`);
+      envMap["GITHUB_TOKEN"] = opts.git.token;
+      envMap["VIAGEN_BRANCH"] = opts.git.branch;
     }
     if (opts.vercel) {
-      envLines.push(`VERCEL_TOKEN=${opts.vercel.token}`);
-      envLines.push(`VERCEL_ORG_ID=${opts.vercel.teamId}`);
-      envLines.push(`VERCEL_PROJECT_ID=${opts.vercel.projectId}`);
+      envMap["VERCEL_TOKEN"] = opts.vercel.token;
+      envMap["VERCEL_ORG_ID"] = opts.vercel.teamId;
+      envMap["VERCEL_PROJECT_ID"] = opts.vercel.projectId;
     }
+    const envLines = Object.entries(envMap).map(([k, v]) => `${k}=${v}`);
     await sandbox2.writeFiles([
       {
         path: ".env",
@@ -297,6 +317,22 @@ async function oauthConsoleFlow() {
   const keyData = await keyRes.json();
   return keyData.raw_key;
 }
+async function refreshAccessToken(refresh) {
+  const res = await fetch(TOKEN_ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      grant_type: "refresh_token",
+      client_id: CLIENT_ID,
+      refresh_token: refresh
+    })
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Token refresh failed (${res.status}): ${text}`);
+  }
+  return await res.json();
+}
 
 // src/cli.ts
 function loadDotenv(dir) {
@@ -334,6 +370,18 @@ function writeEnvVars(dir, vars) {
   content += toAdd.join("\n") + "\n";
   writeFileSync(envPath, content);
 }
+function updateEnvVars(dir, vars) {
+  const envPath = join2(dir, ".env");
+  if (!existsSync(envPath)) return;
+  let content = readFileSync2(envPath, "utf-8");
+  for (const [key, val] of Object.entries(vars)) {
+    const re = new RegExp(`^${key}=.*$`, "m");
+    if (re.test(content)) {
+      content = content.replace(re, `${key}=${val}`);
+    }
+  }
+  writeFileSync(envPath, content);
+}
 function openBrowser2(url) {
   try {
     const platform = process.platform;
@@ -384,6 +432,42 @@ function getGitInfo(cwd) {
     return null;
   }
 }
+function remoteBranchExists(remoteUrl, branch, token) {
+  try {
+    const url = new URL(remoteUrl);
+    url.username = "x-access-token";
+    url.password = token;
+    const out = execSync2(
+      `git ls-remote --heads ${url.toString()} refs/heads/${branch}`,
+      { encoding: "utf-8", stdio: "pipe" }
+    ).trim();
+    return out.length > 0;
+  } catch {
+    return false;
+  }
+}
+function repoNwo(remoteUrl) {
+  const m = remoteUrl.match(/github\.com[/:]([^/]+\/[^/.]+?)(?:\.git)?$/);
+  return m ? m[1] : null;
+}
+function createRemoteBranch(remoteUrl, branch, token) {
+  const nwo = repoNwo(remoteUrl);
+  if (!nwo) return false;
+  try {
+    const sha = execSync2(
+      `gh api repos/${nwo}/git/ref/heads/main --jq .object.sha`,
+      { encoding: "utf-8", stdio: "pipe", env: { ...process.env, GH_TOKEN: token } }
+    ).trim();
+    if (!sha) return false;
+    execSync2(
+      `gh api repos/${nwo}/git/refs -f ref=refs/heads/${branch} -f sha=${sha}`,
+      { encoding: "utf-8", stdio: "pipe", env: { ...process.env, GH_TOKEN: token } }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
 function promptUser(question) {
   if (!process.stdin.isTTY) return Promise.resolve("");
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -650,6 +734,31 @@ async function sandbox(args) {
     );
     process.exit(1);
   }
+  if (hasOAuth && env["CLAUDE_REFRESH_TOKEN"]) {
+    const expires = parseInt(env["CLAUDE_TOKEN_EXPIRES"] || "0", 10);
+    const nowSec = Math.floor(Date.now() / 1e3);
+    if (nowSec > expires - 300) {
+      console.log("Refreshing Claude OAuth tokens...");
+      try {
+        const tokens = await refreshAccessToken(env["CLAUDE_REFRESH_TOKEN"]);
+        env["CLAUDE_ACCESS_TOKEN"] = tokens.access_token;
+        env["CLAUDE_REFRESH_TOKEN"] = tokens.refresh_token;
+        env["CLAUDE_TOKEN_EXPIRES"] = String(nowSec + tokens.expires_in);
+        updateEnvVars(cwd, {
+          CLAUDE_ACCESS_TOKEN: tokens.access_token,
+          CLAUDE_REFRESH_TOKEN: tokens.refresh_token,
+          CLAUDE_TOKEN_EXPIRES: String(nowSec + tokens.expires_in)
+        });
+        console.log("  Tokens refreshed.");
+      } catch (err) {
+        console.error(
+          "Failed to refresh OAuth tokens. Run `npx viagen setup` to re-authenticate."
+        );
+        console.error(`  ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+      }
+    }
+  }
   const hasOidc = !!env["VERCEL_OIDC_TOKEN"];
   const hasToken = !!env["VERCEL_TOKEN"] && !!env["VERCEL_TEAM_ID"] && !!env["VERCEL_PROJECT_ID"];
   if (!hasOidc && !hasToken) {
@@ -664,9 +773,33 @@ async function sandbox(args) {
   let overlayFiles;
   const branch = branchOverride || (gitInfo ? gitInfo.branch : "main");
   if (gitInfo && githubToken) {
+    let branchExistsOnRemote = remoteBranchExists(
+      gitInfo.remoteUrl,
+      branch,
+      githubToken
+    );
+    if (!branchExistsOnRemote) {
+      console.log(
+        `Branch "${branch}" not found on remote \u2014 creating it...`
+      );
+      const created = createRemoteBranch(
+        gitInfo.remoteUrl,
+        branch,
+        githubToken
+      );
+      if (created) {
+        console.log(`  Branch "${branch}" created on remote (from main).`);
+        branchExistsOnRemote = true;
+      } else {
+        console.log(
+          `  Could not create branch on remote \u2014 will clone default branch and create locally.`
+        );
+      }
+    }
     const makeGitInfo = () => ({
       remoteUrl: gitInfo.remoteUrl,
       branch,
+      revision: branchExistsOnRemote ? branch : void 0,
       userName: gitInfo.userName,
       userEmail: gitInfo.userEmail,
       token: githubToken
@@ -718,6 +851,7 @@ async function sandbox(args) {
     } : void 0,
     git: deployGit,
     overlayFiles,
+    envVars: dotenv,
     vercel: env["VERCEL_TOKEN"] && env["VERCEL_TEAM_ID"] && env["VERCEL_PROJECT_ID"] ? {
       token: env["VERCEL_TOKEN"],
       teamId: env["VERCEL_TEAM_ID"],

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 import { Plugin } from 'vite';
 
-declare const DEFAULT_SYSTEM_PROMPT = "You are embedded in a Vite dev server as the \"viagen\" plugin. Your job is to help build and modify the app. Files you edit will trigger Vite HMR automatically. You can read .viagen/server.log to check recent Vite dev server output (compile errors, HMR updates, warnings). When running in a sandbox with git, the gh CLI is available and authenticated \u2014 you can create pull requests, comment on issues, and manage releases. If Vercel credentials are set, you can run \"vercel deploy\" to publish a preview and share the URL. Be concise.";
+declare const DEFAULT_SYSTEM_PROMPT = "You are embedded in a Vite dev server as the \"viagen\" plugin. Your job is to help build and modify the app. Files you edit will trigger Vite HMR automatically. You can read .viagen/server.log to check recent Vite dev server output (compile errors, HMR updates, warnings). When running in a sandbox with git, the gh CLI is available and authenticated \u2014 you can create pull requests, comment on issues, and manage releases.\n\nPublishing workflow:\n- If you are on a feature branch (not main/master): commit your changes, push to the remote, and create a pull request using \"gh pr create\". Share the PR URL.\n- If you are on main/master and Vercel credentials are set ($VERCEL_TOKEN): commit, push, and run \"vercel deploy\" to publish a preview. Share the preview URL.\n- Check your current branch with \"git branch --show-current\" before deciding which workflow to use.\n\nBe concise.";
 
 interface GitInfo {
     /** HTTPS remote URL (transformed from SSH if needed). */
     remoteUrl: string;
     /** Branch to check out. */
     branch: string;
+    /** Revision to clone (branch/tag/sha). If omitted, clones the default branch. */
+    revision?: string;
     /** Git user name for commits. */
     userName: string;
     /** Git user email for commits. */
@@ -40,6 +42,8 @@ interface DeploySandboxOptions {
     };
     /** Sandbox timeout in minutes (default: 30, max depends on Vercel plan). */
     timeoutMinutes?: number;
+    /** User's .env variables to forward into the sandbox. */
+    envVars?: Record<string, string>;
 }
 interface DeploySandboxResult {
     /** Full URL with auth token in query string. */

package/dist/index.js

@@ -1,11 +1,7 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
 // src/index.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname, join as join3 } from "path";
+import { fileURLToPath } from "url";
 import { loadEnv } from "vite";
 
 // src/logger.ts
@@ -59,14 +55,15 @@ function wrapLogger(logger, buffer) {
 }
 
 // src/health.ts
-function registerHealthRoutes(app, env, errorRef) {
-  app.use("/via/error", (_req, res) => {
+function registerHealthRoutes(server, env, errorRef) {
+  server.middlewares.use("/via/error", (_req, res) => {
     res.setHeader("Content-Type", "application/json");
     res.end(JSON.stringify({ error: errorRef.get() }));
   });
-  app.use("/via/health", (_req, res) => {
+  server.middlewares.use("/via/health", (_req, res) => {
     const configured = !!env["ANTHROPIC_API_KEY"] || !!env["CLAUDE_ACCESS_TOKEN"];
     const git = !!env["GITHUB_TOKEN"];
+    const branch = env["VIAGEN_BRANCH"] || null;
     const sessionStart = env["VIAGEN_SESSION_START"] ? parseInt(env["VIAGEN_SESSION_START"], 10) : null;
     const sessionTimeout = env["VIAGEN_SESSION_TIMEOUT"] ? parseInt(env["VIAGEN_SESSION_TIMEOUT"], 10) : null;
     const session = sessionStart && sessionTimeout ? {
@@ -76,10 +73,10 @@ function registerHealthRoutes(app, env, errorRef) {
     } : null;
     res.setHeader("Content-Type", "application/json");
     if (configured) {
-      res.end(JSON.stringify({ status: "ok", configured: true, git, session }));
+      res.end(JSON.stringify({ status: "ok", configured: true, git, branch, session }));
     } else {
       res.end(
-        JSON.stringify({ status: "error", configured: false, git, session })
+        JSON.stringify({ status: "error", configured: false, git, branch, session })
       );
     }
   });
@@ -123,20 +120,27 @@ function readBody(req) {
     req.on("error", reject);
   });
 }
-var DEFAULT_SYSTEM_PROMPT = `You are embedded in a Vite dev server as the "viagen" plugin. Your job is to help build and modify the app. Files you edit will trigger Vite HMR automatically. You can read .viagen/server.log to check recent Vite dev server output (compile errors, HMR updates, warnings). When running in a sandbox with git, the gh CLI is available and authenticated \u2014 you can create pull requests, comment on issues, and manage releases. If Vercel credentials are set, you can run "vercel deploy" to publish a preview and share the URL. Be concise.`;
+var DEFAULT_SYSTEM_PROMPT = `You are embedded in a Vite dev server as the "viagen" plugin. Your job is to help build and modify the app. Files you edit will trigger Vite HMR automatically. You can read .viagen/server.log to check recent Vite dev server output (compile errors, HMR updates, warnings). When running in a sandbox with git, the gh CLI is available and authenticated \u2014 you can create pull requests, comment on issues, and manage releases.
+
+Publishing workflow:
+- If you are on a feature branch (not main/master): commit your changes, push to the remote, and create a pull request using "gh pr create". Share the PR URL.
+- If you are on main/master and Vercel credentials are set ($VERCEL_TOKEN): commit, push, and run "vercel deploy" to publish a preview. Share the preview URL.
+- Check your current branch with "git branch --show-current" before deciding which workflow to use.
+
+Be concise.`;
 function findClaudeBin() {
-  const _require = typeof __require !== "undefined" && typeof __require.resolve === "function" ? __require : createRequire(import.meta.url);
+  const _require = createRequire(import.meta.url);
   const pkgPath = _require.resolve("@anthropic-ai/claude-code/package.json");
   return pkgPath.replace("package.json", "cli.js");
 }
-function registerChatRoutes(app, opts) {
+function registerChatRoutes(server, opts) {
   let sessionId;
-  app.use("/via/chat/reset", (_req, res) => {
+  server.middlewares.use("/via/chat/reset", (_req, res) => {
     sessionId = void 0;
     res.setHeader("Content-Type", "application/json");
     res.end(JSON.stringify({ status: "ok" }));
   });
-  app.use("/via/chat", async (req, res) => {
+  server.middlewares.use("/via/chat", async (req, res) => {
     if (req.method !== "POST") {
       res.statusCode = 405;
       res.end(JSON.stringify({ error: "Method not allowed" }));
@@ -321,7 +325,7 @@ function buildClientScript(opts) {
     /* js */
     `
 (function() {
-  var OVERLAY_ENABLED = ${opts.overlay && (opts.buildTool ?? "vite") === "vite"};
+  var OVERLAY_ENABLED = ${opts.overlay};
   var EMBED_MODE = ${opts.embedMode ? "true" : "false"};
 
   /* ---- Error overlay: inject Fix button into shadow DOM ---- */
@@ -387,7 +391,7 @@ function buildClientScript(opts) {
       var errorData = await errorRes.json();
       if (!errorData.error) { win.classList.remove('viagen-fixing'); return; }
       var e = errorData.error;
-      var prompt = 'Fix this build error in ' +
+      var prompt = 'Fix this Vite build error in ' +
         (e.loc ? e.loc.file + ':' + e.loc.line : 'unknown file') +
         ':\\n\\n' + e.message +
         (e.frame ? '\\n\\nCode frame:\\n' + e.frame : '');
@@ -1136,7 +1140,11 @@ function buildUiHtml() {
     });
     publishBtn.addEventListener('click', function () {
       if (isStreaming) return;
-      inputEl.value = 'Commit all changes, push to the remote repository, and run vercel deploy to get a preview URL';
+      if (publishBtn.dataset.branch && publishBtn.dataset.branch !== 'main' && publishBtn.dataset.branch !== 'master') {
+        inputEl.value = 'Commit all changes, push to the remote branch, and create a pull request using gh pr create. Share the PR URL.';
+      } else {
+        inputEl.value = 'Commit all changes, push to the remote repository, and run vercel deploy to get a preview URL';
+      }
       send();
     });
 
@@ -1186,7 +1194,10 @@ function buildUiHtml() {
         var banner = document.getElementById('setup-banner');
         if (data.configured) {
           dot.className = 'status-dot ok';
-          if (data.git) publishBtn.style.display = '';
+          if (data.git) {
+            publishBtn.style.display = '';
+            if (data.branch) publishBtn.dataset.branch = data.branch;
+          }
         } else {
           dot.className = 'status-dot error';
           inputEl.disabled = true;
@@ -1276,7 +1287,7 @@ function createAuthMiddleware(token) {
       const cleanUrl = url.pathname + (url.search || "");
       res.setHeader(
         "Set-Cookie",
-        `viagen_session=${token}; HttpOnly; SameSite=Strict; Path=/`
+        `viagen_session=${token}; HttpOnly; SameSite=Lax; Path=/; Secure`
       );
       res.writeHead(302, { Location: cleanUrl });
       res.end();
@@ -1329,20 +1340,39 @@ async function deploySandbox(opts) {
   const token = randomUUID();
   const useGit = !!opts.git;
   const timeoutMs = (opts.timeoutMinutes ?? 30) * 60 * 1e3;
-  const sandbox = await Sandbox.create({
-    runtime: "node22",
-    ports: [5173],
-    timeout: timeoutMs,
-    ...opts.git ? {
-      source: {
-        type: "git",
-        url: opts.git.remoteUrl,
-        username: "x-access-token",
-        password: opts.git.token,
-        revision: opts.git.branch
-      }
-    } : {}
-  });
+  const sourceOpts = opts.git ? {
+    source: {
+      type: "git",
+      url: opts.git.remoteUrl,
+      username: "x-access-token",
+      password: opts.git.token,
+      ...opts.git.revision ? { revision: opts.git.revision } : {}
+    }
+  } : {};
+  let sandbox;
+  try {
+    sandbox = await Sandbox.create({
+      runtime: "node22",
+      ports: [5173],
+      timeout: timeoutMs,
+      ...sourceOpts
+    });
+  } catch (err) {
+    console.error("\nSandbox creation failed.");
+    if (opts.git) {
+      console.error(`  URL:      ${opts.git.remoteUrl}`);
+      console.error(`  Revision: ${opts.git.revision ?? "(default branch)"}`);
+      console.error(`  Branch:   ${opts.git.branch}`);
+    }
+    const apiErr = err;
+    if (apiErr.message) console.error(`  Message:  ${apiErr.message}`);
+    if (apiErr.json) {
+      console.error(`  Response: ${JSON.stringify(apiErr.json, null, 2)}`);
+    } else if (apiErr.text) {
+      console.error(`  Response: ${apiErr.text}`);
+    }
+    throw err;
+  }
   try {
     if (useGit && opts.git) {
       await sandbox.runCommand("git", [
@@ -1389,26 +1419,27 @@ async function deploySandbox(opts) {
         await sandbox.writeFiles(files);
       }
     }
-    const envLines = [
-      `VIAGEN_AUTH_TOKEN=${token}`,
-      `VIAGEN_SESSION_START=${Math.floor(Date.now() / 1e3)}`,
-      `VIAGEN_SESSION_TIMEOUT=${(opts.timeoutMinutes ?? 30) * 60}`
-    ];
+    const envMap = { ...opts.envVars ?? {} };
+    envMap["VIAGEN_AUTH_TOKEN"] = token;
+    envMap["VIAGEN_SESSION_START"] = String(Math.floor(Date.now() / 1e3));
+    envMap["VIAGEN_SESSION_TIMEOUT"] = String((opts.timeoutMinutes ?? 30) * 60);
     if (opts.apiKey) {
-      envLines.push(`ANTHROPIC_API_KEY=${opts.apiKey}`);
+      envMap["ANTHROPIC_API_KEY"] = opts.apiKey;
     } else if (opts.oauth) {
-      envLines.push(`CLAUDE_ACCESS_TOKEN=${opts.oauth.accessToken}`);
-      envLines.push(`CLAUDE_REFRESH_TOKEN=${opts.oauth.refreshToken}`);
-      envLines.push(`CLAUDE_TOKEN_EXPIRES=${opts.oauth.tokenExpires}`);
+      envMap["CLAUDE_ACCESS_TOKEN"] = opts.oauth.accessToken;
+      envMap["CLAUDE_REFRESH_TOKEN"] = opts.oauth.refreshToken;
+      envMap["CLAUDE_TOKEN_EXPIRES"] = opts.oauth.tokenExpires;
     }
     if (opts.git) {
-      envLines.push(`GITHUB_TOKEN=${opts.git.token}`);
+      envMap["GITHUB_TOKEN"] = opts.git.token;
+      envMap["VIAGEN_BRANCH"] = opts.git.branch;
     }
     if (opts.vercel) {
-      envLines.push(`VERCEL_TOKEN=${opts.vercel.token}`);
-      envLines.push(`VERCEL_ORG_ID=${opts.vercel.teamId}`);
-      envLines.push(`VERCEL_PROJECT_ID=${opts.vercel.projectId}`);
+      envMap["VERCEL_TOKEN"] = opts.vercel.token;
+      envMap["VERCEL_ORG_ID"] = opts.vercel.teamId;
+      envMap["VERCEL_PROJECT_ID"] = opts.vercel.projectId;
     }
+    const envLines = Object.entries(envMap).map(([k, v]) => `${k}=${v}`);
     await sandbox.writeFiles([
       {
         path: ".env",
@@ -1443,6 +1474,14 @@ async function deploySandbox(opts) {
 }
 
 // src/index.ts
+var docsHtmlCache;
+function getDocsHtml() {
+  if (!docsHtmlCache) {
+    const dir = dirname(fileURLToPath(import.meta.url));
+    docsHtmlCache = readFileSync2(join3(dir, "..", "site", "index.html"), "utf-8");
+  }
+  return docsHtmlCache;
+}
 function viagen(options) {
   const opts = {
     position: options?.position ?? "bottom-right",
@@ -1536,10 +1575,14 @@ ${payload.err.frame || ""}`
         res.setHeader("Content-Type", "text/html");
         res.end(buildIframeHtml({ panelWidth: opts.panelWidth }));
       });
-      registerHealthRoutes(server.middlewares, env, {
+      server.middlewares.use("/via/docs", (_req, res) => {
+        res.setHeader("Content-Type", "text/html");
+        res.end(getDocsHtml());
+      });
+      registerHealthRoutes(server, env, {
         get: () => lastError
       });
-      registerChatRoutes(server.middlewares, {
+      registerChatRoutes(server, {
         env,
         projectRoot,
         logBuffer,