feat: add Docker sbx microVM runtime support

docs/awf-config-spec.md

@@ -183,7 +183,7 @@ AWF settings MAY be supplied via config files, including stdin (`--config -`).
 - `container.dockerHostPathPrefix` → `--docker-host-path-prefix`
 - `container.runnerToolCachePath` → *(config-only; checked first for optional read-only runner tool cache mount, before `RUNNER_TOOL_CACHE` and `/home/runner/work/_tool` auto-detection)*
 - `container.mounts[]` → `-v, --mount` *(repeatable; each array entry maps to one Docker volume mount in `/host_path:/container_path[:ro|rw]` format (both paths must be absolute; host path must exist); in chroot mode, container paths are automatically prefixed with `/host`)*
-- `container.containerRuntime` → `--container-runtime` *(user-facing runtime name, e.g. `"gvisor"`; AWF translates to the Docker OCI runtime identifier, e.g. `"runsc"`. Only the agent container uses the custom runtime; infrastructure containers always use `runc`. When set, AWF injects `extra_hosts` entries for compose-internal services to work around DNS issues with non-default runtimes. Requires the runtime to be installed and registered with Docker on the host.)*
+- `container.containerRuntime` → `--container-runtime` *(user-facing runtime name: `"gvisor"` for OCI runtime in compose, `"sbx"` for Docker sbx microVM. For gvisor: translates to `"runsc"`, injects `extra_hosts` for DNS workaround. For sbx: agent runs in a hypervisor-isolated microVM, infra stays in compose, sbx proxy chains through AWF's Squid.)*
 - `chroot.binariesSourcePath` → *(config-only; overlays a runner-side binaries directory at `/usr/local/bin` inside chroot mode)*
 - `chroot.identity.home` → *(config-only; forwarded as `AWF_CHROOT_IDENTITY_HOME` and applied after chroot pivot)*
 - `chroot.identity.user` → *(config-only; forwarded as `AWF_CHROOT_IDENTITY_USER` and applied to `USER`/`LOGNAME` after chroot pivot)*

docs/awf-config.schema.json

@@ -622,8 +622,8 @@
         },
         "containerRuntime": {
           "type": "string",
-          "enum": ["gvisor"],
-          "description": "Container runtime for the agent container. Set to \"gvisor\" to run the agent under gVisor's runsc runtime for additional sandboxing. Only the agent container uses the custom runtime; infrastructure containers (squid-proxy, api-proxy) always use the default runc runtime. When set, AWF automatically injects extra_hosts entries for compose-internal services to work around DNS resolution issues with non-default runtimes. Requires gVisor (runsc) to be installed and registered with Docker on the host."
+          "enum": ["gvisor", "sbx"],
+          "description": "Container runtime for the agent container. \"gvisor\" runs the agent under gVisor's runsc runtime (OCI runtime, compose-based). \"sbx\" runs the agent inside a Docker sbx microVM with hypervisor isolation; infrastructure containers (squid-proxy, api-proxy) stay in Docker Compose on the host and the sbx proxy chains upstream through AWF's Squid for domain filtering. Only the agent uses the custom runtime; infrastructure containers always use the default runc runtime."
         }
       }
     },

scripts/ci/postprocess-smoke-workflows.ts

@@ -75,14 +75,14 @@ for (const workflowPath of codexWorkflowPaths) {
   }
 }
 
-// ── gVisor workflow: inject --container-runtime gvisor into the AWF command ───
+// ── Runtime workflow patching: inject --container-runtime into AWF commands ───
+// The compiler doesn't support sandbox.agent.containerRuntime yet, so we inject it here.
+const runtimeCmdPattern = /awf --config /g;
+
 const gvisorLockPath = path.join(workflowsDir, 'smoke-gvisor.lock.yml');
 try {
-  let gvisorContent = fs.readFileSync(gvisorLockPath, 'utf-8');
-  // Insert --container-runtime gvisor before --config on the awf command line.
-  // The compiler doesn't support sandbox.agent.containerRuntime yet, so we inject it here.
-  const awfCmdPattern = /awf --config /g;
-  const replacedContent = gvisorContent.replace(awfCmdPattern, 'awf --container-runtime gvisor --config ');
+  const gvisorContent = fs.readFileSync(gvisorLockPath, 'utf-8');
+  const replacedContent = gvisorContent.replace(runtimeCmdPattern, 'awf --container-runtime gvisor --config ');
   if (replacedContent !== gvisorContent) {
     fs.writeFileSync(gvisorLockPath, replacedContent);
     console.log(`  Injected --container-runtime gvisor into AWF command`);
@@ -93,3 +93,19 @@ try {
 } catch {
   console.log(`Skipping ${gvisorLockPath}: file not found.`);
 }
+
+const sbxLockPath = path.join(workflowsDir, 'smoke-docker-sbx.lock.yml');
+try {
+  const sbxContent = fs.readFileSync(sbxLockPath, 'utf-8');
+  runtimeCmdPattern.lastIndex = 0;
+  const sbxReplacedContent = sbxContent.replace(runtimeCmdPattern, 'awf --container-runtime sbx --config ');
+  if (sbxReplacedContent !== sbxContent) {
+    fs.writeFileSync(sbxLockPath, sbxReplacedContent);
+    console.log(`  Injected --container-runtime sbx into AWF command`);
+    console.log(`Updated ${sbxLockPath}`);
+  } else {
+    console.log(`Skipping ${sbxLockPath}: no AWF command found to patch.`);
+  }
+} catch {
+  console.log(`Skipping ${sbxLockPath}: file not found.`);
+}

src/awf-config-schema.json

@@ -622,8 +622,8 @@
         },
         "containerRuntime": {
           "type": "string",
-          "enum": ["gvisor"],
-          "description": "Container runtime for the agent container. Set to \"gvisor\" to run the agent under gVisor's runsc runtime for additional sandboxing. Only the agent container uses the custom runtime; infrastructure containers (squid-proxy, api-proxy) always use the default runc runtime. When set, AWF automatically injects extra_hosts entries for compose-internal services to work around DNS resolution issues with non-default runtimes. Requires gVisor (runsc) to be installed and registered with Docker on the host."
+          "enum": ["gvisor", "sbx"],
+          "description": "Container runtime for the agent container. \"gvisor\" runs the agent under gVisor's runsc runtime (OCI runtime, compose-based). \"sbx\" runs the agent inside a Docker sbx microVM with hypervisor isolation; infrastructure containers (squid-proxy, api-proxy) stay in Docker Compose on the host and the sbx proxy chains upstream through AWF's Squid for domain filtering. Only the agent uses the custom runtime; infrastructure containers always use the default runc runtime."
         }
       }
     },

src/cli-options.ts

@@ -171,9 +171,10 @@ program
   )
   .option(
     '--container-runtime <runtime>',
-    'Container runtime for the agent container (e.g. "gvisor" for gVisor sandboxing).\n' +
-    '                                       AWF translates friendly names to Docker runtime identifiers\n' +
-    '                                       (gvisor → runsc). Unknown values are passed through as-is.'
+   'Container runtime for the agent container.\n' +
+   '                                       "gvisor" — OCI runtime via Docker Compose (translates to runsc).\n' +
+   '                                       "sbx" — Docker sbx microVM with hypervisor isolation.\n' +
+   '                                       Unknown values are passed through as raw Docker runtime names.'
   )
 
   // -- Container Configuration --

src/commands/main-action.test.ts

@@ -33,6 +33,7 @@ jest.mock('../dind-bootstrap');
 jest.mock('./preflight');
 jest.mock('./signal-handler');
 jest.mock('./validate-options');
+jest.mock('../sbx-manager');
 
 import { logger } from '../logger';
 import * as dockerManager from '../docker-manager';
@@ -45,6 +46,7 @@ import * as dindBootstrap from '../dind-bootstrap';
 import * as preflight from './preflight';
 import * as signalHandler from './signal-handler';
 import * as validateOptions from './validate-options';
+import * as sbxManager from '../sbx-manager';
 
 const mockedLogger = logger as jest.Mocked<typeof logger>;
 const mockedDockerManager = dockerManager as jest.Mocked<typeof dockerManager>;
@@ -57,6 +59,7 @@ const mockedDindBootstrap = dindBootstrap as jest.Mocked<typeof dindBootstrap>;
 const mockedPreflight = preflight as jest.Mocked<typeof preflight>;
 const mockedSignalHandler = signalHandler as jest.Mocked<typeof signalHandler>;
 const mockedValidateOptions = validateOptions as jest.Mocked<typeof validateOptions>;
+const mockedSbxManager = sbxManager as jest.Mocked<typeof sbxManager>;
 
 /** Minimal WrapperConfig returned by the validateOptions mock. */
 const STUB_CONFIG = {
@@ -108,6 +111,10 @@ describe('createMainAction', () => {
     mockedDindBootstrap.runDindBootstrap.mockResolvedValue(undefined);
     mockedSignalHandler.registerSignalHandlers.mockImplementation(() => {});
     mockedCliWorkflow.runMainWorkflow.mockResolvedValue(0);
+    mockedSbxManager.isSbxAvailable.mockResolvedValue(true);
+    mockedSbxManager.createSandbox.mockResolvedValue('awf-agent-test');
+    mockedSbxManager.execInSandbox.mockResolvedValue({ exitCode: 0 });
+    mockedSbxManager.removeSandbox.mockResolvedValue(undefined);
   });
 
   afterEach(() => {
@@ -292,6 +299,45 @@ describe('createMainAction', () => {
       await action(['curl https://example.com'], {});
       expect(processExitSpy).toHaveBeenCalledWith(42);
     });
+
+    describe('sbx runtime wiring', () => {
+      it('passes configured mounts/workdir/environment into sbx create/exec', async () => {
+        const sbxConfig = {
+          ...STUB_CONFIG,
+          containerRuntime: 'sbx',
+          containerWorkDir: '/home/runner/work/repo/repo',
+          volumeMounts: ['/tmp/tooling:/tmp/tooling:ro'],
+          enableApiProxy: true,
+          tty: true,
+        } as unknown as import('../types').WrapperConfig;
+        mockedValidateOptions.validateOptions.mockReturnValue(sbxConfig);
+        mockedCliWorkflow.runMainWorkflow.mockImplementation(async (_config, deps, _callbacks) => {
+          await deps.startContainers('/tmp/awf-test', ['github.com']);
+          const result = await deps.runAgentCommand('/tmp/awf-test', ['github.com'], undefined, 10);
+          return result.exitCode;
+        });
+
+        const action = createMainAction(getOptionValueSource);
+        await action(['echo hi'], {});
+
+        expect(mockedSbxManager.createSandbox).toHaveBeenCalledWith(expect.objectContaining({
+          extraMounts: ['/tmp/tooling:/tmp/tooling:ro'],
+        }));
+        expect(mockedSbxManager.execInSandbox).toHaveBeenCalledWith(
+          'awf-agent-test',
+          'echo hi',
+          expect.objectContaining({
+            timeoutMinutes: 10,
+            workDir: '/home/runner/work/repo/repo',
+            tty: true,
+            environment: expect.objectContaining({
+              HTTPS_PROXY: expect.any(String),
+              SQUID_PROXY_HOST: expect.any(String),
+            }),
+          }),
+        );
+      });
+    });
   });
 
   describe('when runMainWorkflow throws', () => {

src/commands/main-action.ts

@@ -26,7 +26,19 @@ import { validateOptions } from './validate-options';
 import { probeSplitFilesystem } from '../dind-probe';
 import { assertTopologySupported, connectTopologyContainers } from '../topology';
 import { runDindBootstrap } from '../dind-bootstrap';
+import { runtimeUsesComposeAgent } from '../container-runtime';
+import { createSandbox, execInSandbox, removeSandbox, isSbxAvailable, SBX_DEFAULT_NAME } from '../sbx-manager';
 import type { WrapperConfig } from '../types';
+import { buildAgentEnvironment } from '../services/agent-service';
+import { buildAgentCredentialEnv } from '../services/api-proxy-credential-env';
+import { DEFAULT_DNS_SERVERS } from '../dns-resolver';
+import { AGENT_IP, CLI_PROXY_IP, DOH_PROXY_IP, SQUID_IP } from '../host-iptables-shared';
+
+/** Report whether a secret is set (and its length) without exposing the value. */
+function redactSecret(value: string | undefined): string {
+  if (!value) return '(unset)';
+  return `(set, len=${value.length})`;
+}
 
 const SENSITIVE_CONFIG_KEYS = new Set([
   'openaiApiKey',
@@ -89,6 +101,15 @@ function buildCleanupFn(
       logger.info(`Received ${signal}, cleaning up...`);
     }
 
+    // Clean up sbx sandbox if using microVM runtime
+    if (!runtimeUsesComposeAgent(config.containerRuntime) && !config.keepContainers) {
+      try {
+        await removeSandbox(SBX_DEFAULT_NAME);
+      } catch {
+        // Sandbox may not exist yet — that's fine
+      }
+    }
+
     // Copy iptables audit BEFORE stopping containers (volumes are destroyed by `docker compose down -v`)
     if (getContainersStarted()) {
       preserveIptablesAudit(config.workDir, config.auditDir);
@@ -231,14 +252,154 @@ export function createMainAction(getOptionValueSource: OptionSourceResolver) {
   });
 
   try {
+    // For sbx (microVM) runtime, wrap startContainers and runAgentCommand
+    // to launch the agent in a sandbox instead of Docker Compose.
+    const useSbx = !runtimeUsesComposeAgent(config.containerRuntime);
+    let sbxName: string | undefined;
+    let sbxEnvironment: Record<string, string> | undefined;
+
+    const sbxStartContainers = useSbx
+      ? async (workDir: string, allowedDomains: string[], proxyLogsDir?: string, skipPull?: boolean, onNetworkReady?: () => Promise<void>) => {
+          // Start infra-only compose (squid, api-proxy — no agent service)
+          await startContainers(workDir, allowedDomains, proxyLogsDir, skipPull, onNetworkReady);
+
+          // Verify sbx is available
+          if (!await isSbxAvailable()) {
+            throw new Error('Docker sbx CLI not found. Install sbx to use --container-runtime sbx.');
+          }
+
+          // For sbx, the microVM can't reach Docker internal IPs (172.30.0.x).
+          // Published Squid port (3128) is accessible via the sbx gateway IP.
+          // The api-proxy is on the awf-ext bridge network and reachable from
+          // inside the sbx via `host.docker.internal` (resolves to the docker0
+          // bridge IP, typically 172.17.0.1).
+          const SBX_GATEWAY_IP = '172.17.0.0';
+          const SBX_HOST_DOCKER_INTERNAL = 'host.docker.internal';
+
+          sbxEnvironment = buildAgentEnvironment({
+            config,
+            networkConfig: {
+              subnet: '172.30.0.0/24',
+              squidIp: SBX_GATEWAY_IP,
+              agentIp: AGENT_IP,
+              proxyIp: config.enableApiProxy ? SBX_HOST_DOCKER_INTERNAL : undefined,
+              dohProxyIp: config.dnsOverHttps ? DOH_PROXY_IP : undefined,
+              cliProxyIp: config.difcProxyHost ? CLI_PROXY_IP : undefined,
+            },
+            dnsServers: config.dnsServers || DEFAULT_DNS_SERVERS,
+          });
+
+          // Merge credential isolation env vars (COPILOT_API_URL, COPILOT_PROVIDER_BASE_URL, etc.)
+          // In Docker mode these are merged by assembleOptionalServices during compose generation.
+          // For sbx, we call buildAgentCredentialEnv directly with host.docker.internal
+          // as the proxy target (the api-proxy is on the awf-ext bridge network).
+          if (config.enableApiProxy) {
+            const credentialEnv = buildAgentCredentialEnv({
+              config,
+              networkConfig: {
+                subnet: '172.30.0.0/24',
+                squidIp: SBX_GATEWAY_IP,
+                agentIp: AGENT_IP,
+                proxyIp: SBX_HOST_DOCKER_INTERNAL,
+              },
+            });
+            Object.assign(sbxEnvironment, credentialEnv);
+          }
+
+          // Log critical env vars for debugging auth flow (redact secret values)
+          logger.info(`[sbx-env] COPILOT_API_URL=${sbxEnvironment.COPILOT_API_URL || '(unset)'}`);
+          logger.info(`[sbx-env] COPILOT_PROVIDER_BASE_URL=${sbxEnvironment.COPILOT_PROVIDER_BASE_URL || '(unset)'}`);
+          logger.info(`[sbx-env] COPILOT_GITHUB_TOKEN=${redactSecret(sbxEnvironment.COPILOT_GITHUB_TOKEN)}`);
+          logger.info(`[sbx-env] COPILOT_API_KEY=${redactSecret(sbxEnvironment.COPILOT_API_KEY)}`);
+          logger.info(`[sbx-env] HTTPS_PROXY=${sbxEnvironment.HTTPS_PROXY || '(unset)'}`);
+          logger.info(`[sbx-env] COPILOT_PROVIDER_API_KEY=${redactSecret(sbxEnvironment.COPILOT_PROVIDER_API_KEY)}`);
+
+          // Create the sandbox with configured mounts, proxy chaining through Squid
+          const workspaceDir = process.env.GITHUB_WORKSPACE || process.cwd();
+          sbxName = await createSandbox({
+            workspaceDir,
+            squidIp: SQUID_IP,
+            extraMounts: config.volumeMounts,
+          });
+
+          // Wait for api-proxy to be healthy before launching agent.
+          // In Docker mode, depends_on: service_healthy gates this; for sbx we poll
+          // via host.docker.internal which resolves to the docker0 bridge from the VM.
+          if (config.enableApiProxy) {
+            logger.info('[sbx] Polling api-proxy health via host.docker.internal...');
+            const healthCmd = [
+              'for i in $(seq 1 30); do',
+              `  if curl -sf --max-time 2 http://${SBX_HOST_DOCKER_INTERNAL}:10000/health >/dev/null 2>&1; then`,
+              '    echo "api-proxy healthy after ${i}s"; exit 0;',
+              '  fi;',
+              '  sleep 1;',
+              'done;',
+              'echo "api-proxy health timeout"; exit 1',
+            ].join(' ');
+
+            const healthResult = await execInSandbox(sbxName, healthCmd, {
+              timeoutMinutes: 1,
+              workDir: config.containerWorkDir,
+              environment: sbxEnvironment,
+            });
+            if (healthResult.exitCode !== 0) {
+              logger.warn('[sbx] api-proxy health check failed — proceeding anyway');
+            }
+          }
+
+          // Verify squid proxy is reachable from sandbox
+          logger.info('[sbx-diag] Verifying squid proxy connectivity...');
+          const diagCmd = [
+            `echo -n "squid ${SBX_GATEWAY_IP}:3128 → "`,
+            `curl -sS --max-time 5 --proxy "http://${SBX_GATEWAY_IP}:3128" -o /dev/null -w "%{http_code}" https://api.github.com/ 2>&1`,
+            'echo ""',
+          ].join(' && ');
+
+          const diagResult = await execInSandbox(sbxName, diagCmd, {
+            timeoutMinutes: 1,
+            workDir: config.containerWorkDir,
+            environment: sbxEnvironment,
+          });
+          logger.info(`[sbx-diag] Connectivity check exited with code ${diagResult.exitCode}`);
+        }
+      : startContainers;
+
+    const sbxRunAgentCommand = useSbx
+      ? async (_workDir: string, _allowedDomains: string[], _proxyLogsDir?: string, agentTimeoutMinutes?: number) => {
+          if (!sbxName) throw new Error('Sandbox not created');
+          logger.info(`[sbx] Launching agent command in sandbox "${sbxName}" (timeout: ${agentTimeoutMinutes ?? 'none'} min)`);
+          logger.debug(`[sbx] Agent command: ${config.agentCommand.substring(0, 200)}...`);
+          const result = await execInSandbox(sbxName, config.agentCommand, {
+            timeoutMinutes: agentTimeoutMinutes,
+            workDir: config.containerWorkDir,
+            environment: sbxEnvironment,
+            tty: config.tty,
+          });
+          logger.info(`[sbx] Agent command exited with code ${result.exitCode}`);
+
+          // Dump api-proxy logs for debugging connection issues
+          if (config.enableApiProxy && result.exitCode !== 0) {
+            try {
+              const { execSync } = await import('child_process');
+              const proxyLogs = execSync('docker logs --tail 80 awf-api-proxy 2>&1', { encoding: 'utf-8', timeout: 10000 });
+              logger.info(`[sbx-diag] api-proxy logs:\n${proxyLogs}`);
+              const healthStatus = execSync('docker inspect --format={{.State.Health.Status}} awf-api-proxy 2>&1', { encoding: 'utf-8', timeout: 5000 });
+              logger.info(`[sbx-diag] api-proxy health status: ${healthStatus.trim()}`);
+            } catch { /* ignore diagnostic failures */ }
+          }
+
+          return { exitCode: result.exitCode, blockedDomains: [] as string[] };
+        }
+      : runAgentCommand;
+
     exitCode = await runMainWorkflow(
       config,
       {
         ensureFirewallNetwork,
         setupHostIptables,
         writeConfigs,
-        startContainers,
-        runAgentCommand,
+        startContainers: sbxStartContainers,
+        runAgentCommand: sbxRunAgentCommand,
         collectDiagnosticLogs,
         assertTopologySupported,
         connectTopologyContainers,