Add modal sandbox support (#192)

* add modal sandbox example

* add test instructions

---------

Co-authored-by: Nathan Flurry <NathanFlurry@users.noreply.github.com>

docs/deploy/modal.mdx

@@ -0,0 +1,97 @@
+---
+title: "Modal"
+description: "Deploy Sandbox Agent inside a Modal sandbox."
+---
+
+## Prerequisites
+
+- `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` from [modal.com/settings](https://modal.com/settings)
+- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
+
+## TypeScript example
+
+```typescript
+import { ModalClient } from "modal";
+import { SandboxAgent } from "sandbox-agent";
+
+const modal = new ModalClient();
+const app = await modal.apps.fromName("sandbox-agent", { createIfMissing: true });
+
+const image = modal.images
+  .fromRegistry("ubuntu:22.04")
+  .dockerfileCommands([
+    "RUN apt-get update && apt-get install -y curl ca-certificates",
+    "RUN curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh",
+  ]);
+
+const envs: Record<string, string> = {};
+if (process.env.ANTHROPIC_API_KEY) envs.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
+if (process.env.OPENAI_API_KEY) envs.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+
+const secrets = Object.keys(envs).length > 0
+  ? [await modal.secrets.fromObject(envs)]
+  : [];
+
+const sb = await modal.sandboxes.create(app, image, {
+  encryptedPorts: [3000],
+  secrets,
+});
+
+const exec = async (cmd: string) => {
+  const p = await sb.exec(["bash", "-c", cmd], { stdout: "pipe", stderr: "pipe" });
+  const exitCode = await p.wait();
+  if (exitCode !== 0) {
+    const stderr = await p.stderr.readText();
+    throw new Error(`Command failed (exit ${exitCode}): ${cmd}\n${stderr}`);
+  }
+};
+
+await exec("sandbox-agent install-agent claude");
+await exec("sandbox-agent install-agent codex");
+
+await sb.exec(
+  ["bash", "-c", "sandbox-agent server --no-token --host 0.0.0.0 --port 3000 &"],
+);
+
+const tunnels = await sb.tunnels();
+const baseUrl = tunnels[3000].url;
+
+const sdk = await SandboxAgent.connect({ baseUrl });
+
+const session = await sdk.createSession({ agent: "claude" });
+const off = session.onEvent((event) => {
+  console.log(event.sender, event.payload);
+});
+
+await session.prompt([{ type: "text", text: "Summarize this repository" }]);
+off();
+
+await sb.terminate();
+```
+
+## Faster cold starts
+
+Modal caches image layers, so the `dockerfileCommands` that install `curl` and `sandbox-agent` only run on the first build. Subsequent sandbox creates reuse the cached image.
+
+## Running the test
+
+The example includes a health-check test. First, build the SDK:
+
+```bash
+pnpm --filter sandbox-agent build
+```
+
+Then run the test with your Modal credentials:
+
+```bash
+MODAL_TOKEN_ID=<your-token-id> MODAL_TOKEN_SECRET=<your-token-secret> npx vitest run
+```
+
+Run from `examples/modal/`. The test will skip if credentials are not set.
+
+## Notes
+
+- Modal sandboxes use [gVisor](https://gvisor.dev/) for strong isolation.
+- Ports are exposed via encrypted tunnels (`encryptedPorts`). Use `sb.tunnels()` to get the public HTTPS URL.
+- Environment variables (API keys) are passed as Modal [Secrets](https://modal.com/docs/guide/secrets) rather than plain env vars for security.
+- Always call `sb.terminate()` when done to avoid leaking sandbox resources.