sandbox docs (#698)

* sandbox docs

* format

docs/src/app/next/page.mdx

@@ -16,23 +16,58 @@ pnpm add @vercel/sandbox
 
 ## Server action
 
+The Vercel Sandbox runs Amazon Linux. Chromium requires system libraries
+that are not installed by default, so fresh sandboxes need a `dnf install`
+step before agent-browser can launch Chrome. Use a sandbox snapshot
+(below) to skip this entirely in production.
+
 ```ts
 "use server";
 import { Sandbox } from "@vercel/sandbox";
 
 const snapshotId = process.env.AGENT_BROWSER_SNAPSHOT_ID;
 
+const CHROMIUM_SYSTEM_DEPS = [
+  "nss", "nspr", "libxkbcommon", "atk", "at-spi2-atk", "at-spi2-core",
+  "libXcomposite", "libXdamage", "libXrandr", "libXfixes", "libXcursor",
+  "libXi", "libXtst", "libXScrnSaver", "libXext", "mesa-libgbm", "libdrm",
+  "mesa-libGL", "mesa-libEGL", "cups-libs", "alsa-lib", "pango", "cairo",
+  "gtk3", "dbus-libs",
+];
+
+function getSandboxCredentials() {
+  if (
+    process.env.VERCEL_TOKEN &&
+    process.env.VERCEL_TEAM_ID &&
+    process.env.VERCEL_PROJECT_ID
+  ) {
+    return {
+      token: process.env.VERCEL_TOKEN,
+      teamId: process.env.VERCEL_TEAM_ID,
+      projectId: process.env.VERCEL_PROJECT_ID,
+    };
+  }
+  return {};
+}
+
 async function withBrowser<T>(
   fn: (sandbox: InstanceType<typeof Sandbox>) => Promise<T>,
 ): Promise<T> {
+  const credentials = getSandboxCredentials();
+
   const sandbox = snapshotId
     ? await Sandbox.create({
+        ...credentials,
         source: { type: "snapshot", snapshotId },
         timeout: 120_000,
       })
-    : await Sandbox.create({ runtime: "node24", timeout: 120_000 });
+    : await Sandbox.create({ ...credentials, runtime: "node24", timeout: 120_000 });
 
   if (!snapshotId) {
+    await sandbox.runCommand("sh", [
+      "-c",
+      `sudo dnf clean all 2>&1 && sudo dnf install -y --skip-broken ${CHROMIUM_SYSTEM_DEPS.join(" ")} 2>&1 && sudo ldconfig 2>&1`,
+    ]);
     await sandbox.runCommand("npm", ["install", "-g", "agent-browser"]);
     await sandbox.runCommand("npx", ["agent-browser", "install"]);
   }
@@ -48,13 +83,15 @@ export async function screenshotUrl(url: string) {
   return withBrowser(async (sandbox) => {
     await sandbox.runCommand("agent-browser", ["open", url]);
 
-    const result = await sandbox.runCommand("agent-browser", [
+    const ssResult = await sandbox.runCommand("agent-browser", [
       "screenshot", "--json",
     ]);
-    const data = JSON.parse(await result.stdout());
+    const ssPath = JSON.parse(await ssResult.stdout())?.data?.path;
+    const b64Result = await sandbox.runCommand("base64", ["-w", "0", ssPath]);
+    const screenshot = (await b64Result.stdout()).trim();
 
     await sandbox.runCommand("agent-browser", ["close"]);
-    return { ok: true, screenshot: data.data.base64 };
+    return { ok: true, screenshot };
   });
 }
 
@@ -75,11 +112,12 @@ export async function snapshotUrl(url: string) {
 
 ## Sandbox snapshots
 
-Without optimization, each Sandbox run installs agent-browser + Chromium
-from scratch (~30 seconds). A **sandbox snapshot** is a saved VM image
-with everything pre-installed -- like a Docker image for Vercel Sandbox.
-When `AGENT_BROWSER_SNAPSHOT_ID` is set, the sandbox boots from that
-image instead of installing, bringing startup down to sub-second.
+Without optimization, each Sandbox run installs system dependencies +
+agent-browser + Chromium from scratch (~30 seconds). A **sandbox snapshot**
+is a saved VM image with everything pre-installed -- like a Docker image
+for Vercel Sandbox. When `AGENT_BROWSER_SNAPSHOT_ID` is set, the sandbox
+boots from that image instead of installing, bringing startup down to
+sub-second.
 
 This is different from an agent-browser *accessibility snapshot* (which
 dumps a page's accessibility tree). A sandbox snapshot is a Vercel
@@ -91,8 +129,8 @@ Create a sandbox snapshot by running the helper script once:
 npx tsx scripts/create-snapshot.ts
 ```
 
-The script spins up a fresh sandbox, installs agent-browser + Chromium,
-saves the VM state, and prints the snapshot ID:
+The script spins up a fresh sandbox, installs system dependencies +
+agent-browser + Chromium, saves the VM state, and prints the snapshot ID:
 
 ```
 AGENT_BROWSER_SNAPSHOT_ID=snap_xxxxxxxxxxxx
@@ -101,6 +139,25 @@ AGENT_BROWSER_SNAPSHOT_ID=snap_xxxxxxxxxxxx
 Add this to your Vercel project environment variables (or `.env.local`
 for local development). Recommended for any production deployment.
 
+## Authentication
+
+On Vercel deployments, the Sandbox SDK authenticates automatically via
+OIDC. For local development, provide explicit credentials:
+
+<table>
+  <thead>
+    <tr><th>Variable</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>VERCEL_TOKEN</code></td><td>Vercel personal access token</td></tr>
+    <tr><td><code>VERCEL_TEAM_ID</code></td><td>Vercel team ID</td></tr>
+    <tr><td><code>VERCEL_PROJECT_ID</code></td><td>Vercel project ID</td></tr>
+  </tbody>
+</table>
+
+When all three are set, they are passed to `Sandbox.create()`. When
+absent, the SDK falls back to `VERCEL_OIDC_TOKEN` (automatic on Vercel).
+
 ## Scheduled workflows (cron)
 
 For recurring tasks like daily monitoring, use Vercel Cron Jobs:
@@ -141,10 +198,14 @@ export async function GET() {
   </thead>
   <tbody>
     <tr><td><code>AGENT_BROWSER_SNAPSHOT_ID</code></td><td>Sandbox snapshot ID for sub-second startup (see above)</td></tr>
+    <tr><td><code>VERCEL_TOKEN</code></td><td>Vercel personal access token (for local dev; OIDC is automatic on Vercel)</td></tr>
+    <tr><td><code>VERCEL_TEAM_ID</code></td><td>Vercel team ID (for local dev)</td></tr>
+    <tr><td><code>VERCEL_PROJECT_ID</code></td><td>Vercel project ID (for local dev)</td></tr>
   </tbody>
 </table>
 
 ## Demo app
 
-A working demo with a UI and deploy-to-Vercel button is at
+A working demo with streaming progress UI, rate limiting, and a
+deploy-to-Vercel button is at
 [`examples/environments/`](https://github.com/agent-browser/agent-browser/tree/main/examples/environments).