Restore Superserve sandbox blueprint and docs for the current adapter API

apps/docs/src/content/docs/ecosystem/sandboxes/superserve.md

@@ -0,0 +1,71 @@
+---
+title: Superserve
+description: Connect a Flue agent to an application-owned Superserve sandbox.
+lastReviewedAt: 2026-06-18
+---
+
+The Superserve adapter adapts an already-initialized Superserve sandbox from the `@superserve/sdk` package into Flue's sandbox interface. Use it for provider-managed Firecracker microVM execution when an agent needs shell commands and workspace files that persist across a session.
+
+## Quickstart
+
+Add provider-managed Linux sandbox capability to an existing Flue project with the [Superserve](https://superserve.ai) blueprint. Run the following command in your terminal or coding agent of choice:
+
+```bash
+flue add sandbox superserve
+```
+
+## Overview
+
+The Superserve blueprint installs `@superserve/sdk` when needed and creates `sandboxes/superserve.ts` in your source-root. The generated adapter accepts an application-created Superserve `Sandbox`; provisioning, template selection, credentials, and shutdown remain outside the adapter.
+
+```ts title="<source-root>/sandboxes/superserve.ts (abridged)"
+// flue-blueprint: sandbox/superserve@1
+import { createSandboxSessionEnv } from '@flue/runtime';
+import type { SandboxApi, SandboxFactory, SessionEnv, FileStat } from '@flue/runtime';
+import type { Sandbox as SuperserveSandbox } from '@superserve/sdk';
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+class SuperserveSandboxApi implements SandboxApi {
+  constructor(private sandbox: SuperserveSandbox) {}
+
+  /* Reads and writes files with sandbox.files.readText, read, and write. */
+
+  /* Implements stat, readdir, exists, mkdir, and rm with quoted GNU shell utilities. */
+
+  /* Runs commands with sandbox.commands.run(), forwards timeoutMs and signal, and maps a timeout to exit code 124. */
+}
+
+export function superserve(sandbox: SuperserveSandbox): SandboxFactory {
+  return {
+    async createSessionEnv(): Promise<SessionEnv> {
+      const sandboxCwd = '/home/user';
+      const api = new SuperserveSandboxApi(sandbox);
+      return createSandboxSessionEnv(api, sandboxCwd);
+    },
+  };
+}
+```
+
+Passing `superserve(sandbox)` as an agent's `sandbox` exposes the created Superserve sandbox's files and command execution through Flue, with relative paths rooted at `/home/user`. File reads and writes use Superserve's data-plane file API; `stat`, `readdir`, `exists`, `mkdir`, and `rm` shell out, so the sandbox's template must provide GNU coreutils, which the default `superserve/base` image (Ubuntu 24.04) does. The generated `rm` receives the requested recursive and force flags, and a command that exceeds its `timeoutMs` resolves to exit code `124` rather than throwing.
+
+`superserve/base` is otherwise minimal — `git`, `curl`, and coreutils on Ubuntu 24.04, with no language runtimes. When the agent shells out to tooling such as `node` or `python`, boot from a curated template like `superserve/node-22` or `superserve/python-3.11`, or a custom template, via `Sandbox.create({ fromTemplate })`.
+
+## Configure
+
+| Variable              | Purpose                                                              |
+| --------------------- | ------------------------------------------------------------------- |
+| `SUPERSERVE_API_KEY`  | **Required** — Authenticates the SDK with the Superserve control plane; read from the environment automatically. |
+
+| Requirement                 | Purpose                                                                                       |
+| --------------------------- | -------------------------------------------------------------------------------------------- |
+| `@superserve/sdk` package   | **Required** — Provides the Superserve TypeScript SDK.                                        |
+| Template with GNU coreutils | **Required** — Provides the shell utilities used for filesystem operations the SDK does not expose. |
+
+## Choose this adapter when
+
+Use Superserve when your application already manages Superserve sandbox lifetimes — creation, pausing, templates, and shutdown — and needs to expose that microVM boundary to Flue operations. The adapter adapts the created sandbox; creation, shutdown, secret handling, networking, and template content remain your responsibility.
+
+See [Sandboxes](/docs/guide/sandboxes/) and [Sandbox Adapter API](/docs/api/sandbox-api/).

apps/docs/src/lib/docs-navigation.ts

@@ -211,6 +211,7 @@ export const docsSections: DocsSection[] = [
 					{ title: 'islo', slug: 'ecosystem/sandboxes/islo' },
 					{ title: 'Mirage', slug: 'ecosystem/sandboxes/mirage' },
 					{ title: 'Modal', slug: 'ecosystem/sandboxes/modal' },
+					{ title: 'Superserve', slug: 'ecosystem/sandboxes/superserve' },
 					{ title: 'Vercel Sandbox', slug: 'ecosystem/sandboxes/vercel' },
 				],
 			},

apps/ecosystem-catalog.ts

@@ -32,6 +32,9 @@ const braintrustIcon = svgDataUri(
 const openTelemetryIcon = svgDataUri(
 	'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill="#f5a800" d="M67.648 69.797c-5.246 5.25-5.246 13.758 0 19.008 5.25 5.246 13.758 5.246 19.004 0 5.25-5.25 5.25-13.758 0-19.008-5.246-5.246-13.754-5.246-19.004 0Zm14.207 14.219a6.649 6.649 0 0 1-9.41 0 6.65 6.65 0 0 1 0-9.407 6.649 6.649 0 0 1 9.41 0c2.598 2.586 2.598 6.809 0 9.407ZM86.43 3.672l-8.235 8.234a4.17 4.17 0 0 0 0 5.875l32.149 32.149a4.17 4.17 0 0 0 5.875 0l8.234-8.235c1.61-1.61 1.61-4.261 0-5.87L92.29 3.671a4.159 4.159 0 0 0-5.86 0ZM28.738 108.895a3.763 3.763 0 0 0 0-5.31l-4.183-4.187a3.768 3.768 0 0 0-5.313 0l-8.644 8.649-.016.012-2.371-2.375c-1.313-1.313-3.45-1.313-4.75 0-1.313 1.312-1.313 3.449 0 4.75l14.246 14.242a3.353 3.353 0 0 0 4.746 0c1.3-1.313 1.313-3.45 0-4.746l-2.375-2.375.016-.012Zm43.559-81.582L54.004 45.605c-1.625 1.625-1.625 4.301 0 5.926L65.3 62.824c7.984-5.746 19.18-5.035 26.363 2.153l9.148-9.149c1.622-1.625 1.622-4.297 0-5.922L78.22 27.313a4.185 4.185 0 0 0-5.922 0ZM60.55 67.585l-6.672-6.672c-1.563-1.562-4.125-1.562-5.684 0l-23.53 23.54a4.036 4.036 0 0 0 0 5.687l13.331 13.332a4.036 4.036 0 0 0 5.688 0l15.132-15.157c-3.199-6.609-2.625-14.593 1.735-20.73Z"/></svg>',
 );
+const superserveIcon = svgDataUri(
+	'<svg viewBox="0 0 130 130" fill="none" xmlns="http://www.w3.org/2000/svg"> <path d="M0.122855 69.0294C0.0413498 67.6967 0 66.3532 0 65C0 63.8414 0.0303123 62.6899 0.0901869 61.5462H26.0078C25.9083 62.6843 25.8574 63.8361 25.8574 65C25.8574 66.3604 25.9268 67.7047 26.0623 69.0294H0.122855Z" fill="#B2FAB4"/> <path d="M2.81957 83.9956C2.07611 81.5589 1.47195 79.0615 1.01638 76.5125H27.5778C28.3837 79.1349 29.4576 81.64 30.7677 83.9956H30.7058L12.0261 102.675C10.5438 100.595 9.18103 98.4235 7.94775 96.171L20.1231 83.9956H2.81957Z" fill="#B2FAB4"/> <path d="M22.3125 114.019C20.4303 112.379 18.6435 110.632 16.9615 108.788L35.278 90.4712C36.9051 92.3681 38.7106 94.1076 40.6685 95.6633L22.3125 114.019Z" fill="#B2FAB4"/> <path d="M34.5772 122.456C32.3013 121.248 30.1058 119.909 28.0006 118.449L46.58 99.8698V99.5463C49.0281 100.854 51.6313 101.91 54.3551 102.678L54.0631 102.97V129.084C51.5152 128.652 49.0178 128.072 46.58 127.353V110.453L34.5772 122.456Z" fill="#B2FAB4"/> <path d="M69.0294 129.877C67.6967 129.959 66.3532 130 65 130C63.8414 130 62.6899 129.97 61.5462 129.91V103.992C62.6843 104.092 63.8361 104.143 65 104.143C66.3604 104.143 67.7047 104.073 69.0294 103.938V129.877Z" fill="#B2FAB4"/> <path d="M83.9956 127.18C81.5589 127.924 79.0615 128.528 76.5125 128.984V102.97L76.0917 102.549C78.8673 101.73 81.5141 100.612 83.9956 99.2323V99.8701L102.338 118.213C100.245 119.684 98.0619 121.035 95.7978 122.255L83.9956 110.453V127.18Z" fill="#B2FAB4"/> <path d="M113.584 108.182C111.925 110.047 110.16 111.816 108.299 113.48L89.9669 95.1476C91.8911 93.5522 93.6599 91.7762 95.2476 89.8455L113.584 108.182Z" fill="#B2FAB4"/> <path d="M122.255 95.7981C121.034 98.0622 119.684 100.246 118.212 102.338L99.8698 83.9956H99.2323C100.612 81.5144 101.73 78.867 102.549 76.0917L102.969 76.5125H128.984C128.528 79.0615 127.924 81.5589 127.18 83.9956H110.453L122.255 95.7981Z" fill="#B2FAB4"/> <path d="M129.91 61.5462C129.97 62.6899 130 63.8414 130 65C130 66.3532 129.959 67.6967 129.877 69.0294H103.938C104.073 67.7047 104.143 66.3604 104.143 65C104.143 63.8361 104.092 62.6843 103.992 61.5462H129.91Z" fill="#B2FAB4"/> <path d="M122.455 34.577L110.453 46.58H127.353C128.072 49.0178 128.652 51.5152 129.084 54.0631H102.969L102.678 54.3548C101.91 51.631 100.854 49.0278 99.5463 46.58H99.8698L118.449 28.0006C119.909 30.1057 121.248 32.3012 122.455 34.577Z" fill="#B2FAB4"/> <path d="M108.788 16.9615C110.632 18.6435 112.379 20.4303 114.019 22.3125L95.6633 40.6685C94.1076 38.7106 92.3681 36.9051 90.4712 35.278L108.788 16.9615Z" fill="#B2FAB4"/> <path d="M96.171 7.94775C98.4235 9.18103 100.595 10.5438 102.675 12.0261L83.9956 30.7058V30.7677C81.64 29.4576 79.1349 28.3837 76.5125 27.5778V1.01638C79.0615 1.47195 81.5589 2.07611 83.9956 2.81957V20.1231L96.171 7.94775Z" fill="#B2FAB4"/> <path d="M61.5462 0.0901869C62.6899 0.0303123 63.8414 0 65 0C66.3532 0 67.6967 0.0413498 69.0294 0.122855V26.0623C67.7047 25.9268 66.3604 25.8574 65 25.8574C63.8361 25.8574 62.6843 25.9083 61.5462 26.0078V0.0901869Z" fill="#B2FAB4"/> <path d="M46.58 2.64688C49.0178 1.92784 51.5152 1.34788 54.0631 0.916179V27.4058C51.3842 28.1838 48.824 29.2403 46.4158 30.542L27.6615 11.7877C29.7543 10.3165 31.9377 8.96567 34.2018 7.74522L46.58 20.1234V2.64688Z" fill="#B2FAB4"/> <path d="M7.74508 34.2021C8.96552 31.938 10.3163 29.7545 11.7875 27.6618L30.542 46.4161C29.2403 48.8243 28.1838 51.3845 27.4058 54.0631H0.916179C1.34788 51.5152 1.92784 49.0178 2.64688 46.58H20.1231L7.74508 34.2021Z" fill="#B2FAB4"/> <path d="M40.1545 34.7524C38.2238 36.3401 36.4478 38.1089 34.8524 40.0331L16.6474 21.828L21.9388 16.5367L40.1545 34.7524Z" fill="#B2FAB4"/> </svg>',
+);
 
 export const channels: EcosystemItem[] = [
 	{
@@ -277,6 +280,14 @@ export const sandboxes: EcosystemItem[] = [
 		background: '#ffffff',
 	},
 	{ name: 'smolvm', href: '/docs/ecosystem/sandboxes/smolvm/', background: '#2563eb' },
+	{
+		name: 'Superserve',
+		href: '/docs/ecosystem/sandboxes/superserve/',
+		icon: superserveIcon,
+		background: '#0d0d0d',
+		iconClass: 'ecosystem-logo-small',
+		keywords: 'superserve sandbox firecracker microvm',
+	},
 	{
 		name: 'Vercel Sandbox',
 		href: '/docs/ecosystem/sandboxes/vercel/',