Skip to content

ai-sdk-microsandbox-v0.0.1

Pre-release
Pre-release

Choose a tag to compare

View all tags
@github-actions github-actions released this 18 Jun 12:23
· 18 commits to main since this release
ai-sdk-microsandbox-v0.0.1
10e70f4
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

First public release of ai-sdk-microsandbox.

A Vercel AI SDK v7 HarnessV1SandboxProvider backed by microsandbox. Drop-in alternative to @ai-sdk/sandbox-vercel at the sandbox: slot of HarnessAgent, running coding agents in local microVM isolation instead of Vercel-hosted sandboxes. The bridge, the agent CLI, and any files the agent touches stay on-host. Cross-process resume works via an on-disk snapshot cache.

Install

npm install ai-sdk-microsandbox @ai-sdk/harness @ai-sdk/harness-codex ai microsandbox

Quickstart

import { HarnessAgent } from '@ai-sdk/harness/agent'
import { createCodex } from '@ai-sdk/harness-codex'
import { createMicrosandbox } from 'ai-sdk-microsandbox'

const agent = new HarnessAgent({
  harness: createCodex({
    auth: { openai: { apiKey: process.env.OPENAI_API_KEY } },
  }),
  sandbox: createMicrosandbox({
    image: 'node:22-bookworm-slim',
    cpus: 1,
    memory: 1024,
    workdir: '/root',
    ports: [{ host: 4000, guest: 4000 }],
    bootstrapPreCommands: [
      'apt-get update -qq && apt-get install -y --no-install-recommends ca-certificates >/dev/null && update-ca-certificates -f >/dev/null',
      'corepack enable pnpm',
    ],
  }),
})

const session = await agent.createSession()
try {
  const result = await agent.generate({
    session,
    prompt: 'Use bash to create /root/hi.txt containing "hello".',
  })
  console.log(result.text)
} finally {
  await session.destroy()
}

Requirements

  • Linux with KVM enabled, or macOS on Apple Silicon
  • Run microsandbox setup once on the host

Verified end-to-end

This release was validated against real Codex turns through real OpenAI on a clean machine:

  • Unit suite: 216 / 216 pass
  • Integration suite (real microVM): 23 / 23 pass
  • E2E suite (real Codex + real OpenAI): 15 / 15 pass

Covers: text generation, streaming, bash tool through the bridge, file I/O round-trips, multi-turn context preservation, distinct sandboxes per session, cross-process resume via session.detach() + agent.createSession({ resumeFrom }), abort cancellation, and the configuration matrix (workdir, env, cpus, memory, network policy).

What's in the box

  • createMicrosandbox(settings) provider with both create-mode (fresh microVM per session) and wrap-mode (caller-owned sandbox)
  • Filesystem-level snapshot cache keyed on a stable identity hash so the bootstrap recipe runs once per identity across processes
  • bootstrapPreCommands setting for image-prep steps (e.g. corepack enable pnpm, apt-get install ca-certificates) that get captured into the snapshot
  • resumeSession implementation that dispatches between handle.connect() (running) and handle.start() (stopped) so resume works for both detach() and stop() payloads
  • Network policy translation (allow-all / deny-all / custom with allowedHosts, allowedCIDRs, deniedCIDRs) into microsandbox's NetworkPolicyBuilder at create-time
  • Configurable cache root via AI_SDK_MICROSANDBOX_CACHE_DIR; defaults to the OS-conventional cache directory

Status and limitations

  • Alpha. The exported API may shift before 1.0.0.
  • Runtime network policy updates are unavailable; policy is sealed at create-time.
  • Concurrent multi-session usage on one provider is bounded by the host-port mapping (two forks cannot bind the same host port simultaneously).
  • Snapshot pruning is manual today; remove the cache directory to reset.
  • The chosen workdir must already exist in the image, or be created via bootstrapPreCommands.

Links

Assets 2
Loading