Add microsandbox sandbox blueprint and ecosystem entry

[appcypher]

RFC

Summary

Add a microsandbox sandbox blueprint and ecosystem entry for Flue Node projects. The adapter wraps an application-created microsandbox Sandbox in Flue's SandboxApi, so agents get a local Linux microVM workspace without standing up a separate hosted sandbox service.

Background & Motivation

Flue's sandbox model already keeps the harness separate from the execution environment, which is nice to work with. Reading the Sandboxes guide, the options today are the virtual just-bash sandbox for lightweight work, local() for trusted host access, and provider-backed remote sandboxes when work needs real isolation or a managed lifecycle.

The docs are clear that the virtual sandbox is "not a network isolation boundary" and that local() "does not provide isolation between model-directed work and the host." So as soon as an agent runs untrusted, model-directed shell steps, the only isolated option is to leave the machine and use a hosted provider, even for local dev and CI. There isn't a tier that is both a real isolation boundary and runnable locally without a third-party account.

microsandbox fills that spot. It's an open source (Apache-2.0) cross-platform microVM sandbox runtime with a native Node.js SDK (Node 22+, which matches Flue's engine floor). It boots OCI images into a guest Linux kernel and, by default, runs embedded and local: you get hardware isolation from npm install microsandbox, with no account, no API key, and no network hop.

This seems most useful for self-hosted Flue deployments, repo and CI agents, privacy-sensitive setups, and teams that want stronger isolation than local() but don't want to depend on an external sandbox service. From Flue's side it's a normal sandbox adapter, not a runtime change. The app still owns lifecycle, image choice, resources, network policy, secrets, and cleanup, and Flue just receives a SandboxFactory from createSandboxSessionEnv(...).

Goals

• Add flue add sandbox microsandbox.
• Document microsandbox in the ecosystem sandbox catalog (page, sidebar entry, logo).
• Adapt an existing microsandbox Sandbox into Flue's SandboxApi, keeping lifecycle application-owned to match the current adapter contract.
• Honor the cancellation contract: forward timeoutMs to the SDK's native .timeout(), and wire signal to the exec handle's .signal() / .kill() for real mid-flight cancellation.
• Make setup requirements explicit: Node 22+, the microsandbox npm package, and a supported local environment (Linux (needs KVM enabled), macOS (requires Apple Silicon), and Windows (needs WHP enabled)).
• Give Flue users a local, isolated Linux backend that is stronger than local() but lighter to adopt than an external hosted provider.

Example

import { defineAgent } from '@flue/runtime';
import { GiB, NetworkPolicy, Sandbox } from 'microsandbox';
import { microsandbox } from '../sandboxes/microsandbox';

export default defineAgent(async ({ id }) => {
  const sandbox = await Sandbox.builder(`flue-${id}`)
    .image('node:22-bookworm')
    .cpus(2)
    .memory(GiB(1))
    .network((n) => n.policy(NetworkPolicy.publicOnly()))
    .replace()
    .create();

  return {
    model: 'anthropic/claude-sonnet-4-6',
    sandbox: microsandbox(sandbox, { cwd: '/workspace' }),
  };
});

The adapter maps microsandbox filesystem operations to readFile, readFileBuffer, writeFile, stat, readdir, exists, mkdir, and rm, and uses execWith('sh', ...) with sh -lc for Flue shell commands so cwd, env, and timeoutMs are honored. The shape lines up closely with the existing adapter contract, so it's a small adapter rather than anything invasive:

Happy to help with the implementation if this sounds like a good fit. For transparency, I work on microsandbox, so I'm glad to write the blueprint and adapter.

[astrobot-houston]

Possibly related contribution from @Hor1zonZzz — opened #427 which appears to be addressing this.

Their summary: Adds Microsandbox as a new sandbox provider blueprint, enabling flue add sandbox microsandbox for a self-hosted, hardware-isolated microVM sandbox option. Includes the SandboxApi adapter implementation guide, ecosystem catalog entry, and documentation page.

Implementation: Hor1zonZzz/flue@add-microsandbox-sandbox-blueprint (diff)

This comment was posted automatically when #427 was redirected. The implementation is preserved on the branch above so it can inform the work here.