kosa8

kosa8 / Guides

Guide · Updated 2026-10-31

How do I run Vercel AI SDK agent code in a local sandbox?

Install @kosa8/ai-sdk-sandbox, create a session with createKosa8NetworkSandboxSession, and pass session.restricted() to generateText as experimental_sandbox. Your tools then run commands and file operations in a kosa8 microVM on your own machine. The package implements AI SDK 7's sandbox interfaces in the same shape as @ai-sdk/sandbox-vercel and @e2b/ai-sdk-sandbox, and needs no account or API key for the sandbox.

01Steps

  1. Install kosa8 and start the daemon. On an Apple silicon Mac or x86-64 Linux, with Node.js 22 or later for the package.

  2. Install the adapter. kosa8's docs test it with [email protected]. zod is for the tool schemas below.

  3. Create a session and give tools the restricted view. Each session is one microVM. restricted() is a frozen object with only description, the file methods, run and spawn: code holding it cannot stop the sandbox or change its network. Tools receive it as experimental_sandbox.

    agent.mjs
    import { generateText, stepCountIs, tool } from 'ai';
import { z } from 'zod';
import { createKosa8NetworkSandboxSession } from '@kosa8/ai-sdk-sandbox';
 
const session = await createKosa8NetworkSandboxSession({
  image: 'node:22-alpine',
  networkPolicy: { mode: 'custom', allowedHosts: ['registry.npmjs.org'] },
});
try {
  const sandbox = session.restricted();
  const result = await generateText({
    model,                        // any AI SDK model
    stopWhen: stepCountIs(10),
    prompt: `Run the tests.\n\nSandbox:\n${sandbox.description}`,
    experimental_sandbox: sandbox,
    tools: {
      shell: tool({
        description: 'Run a shell command in the sandbox.',
        inputSchema: z.object({ command: z.string() }),
        execute: ({ command }, { experimental_sandbox, abortSignal }) =>
          experimental_sandbox.run({ command, abortSignal }),
      }),
    },
  });
  console.log(result.text);
} finally {
  await session.destroy();        // deletes the microVM
}

  4. End the script cleanly on version 0.1.0. kosa8's docs record a known issue in 0.1.0: after run, spawn, kill() or an abort, an exec socket can stay open, so Node keeps running after your last line. They say 0.1.1 fixes it. On 0.1.0, end scripts with process.exit(0).

02How do AI SDK network policies map to kosa8 egress?

allow-all becomes any, deny-all refuses every outbound connection, and custom with allowedHosts and allowedCIDRs becomes a kosa8 allow-list, *.domain wildcards included, enforced on the host. deniedCIDRs throws, because kosa8's egress is an allow-list and anything not listed is already refused.

If you set neither networkPolicy nor kosa8's own egress, the daemon applies the org policy's default egress, or unrestricted access when there is none. The work container's image is pulled through the host, so deny-all sessions still start.

03What can't the kosa8 AI SDK sandbox do?

It cannot change a running session's network policy, expose ports (getPortEndpoint and setPorts throw, and ports is empty), give spawn stdin or a pid, or provide request transformations. Each unsupported call throws the AI SDK's HarnessCapabilityUnsupportedError rather than doing nothing.

For credentials, configure kosa8's egress broker with the broker setting at creation. Checkpoints and fork are not part of the AI SDK interface; use @kosa8/sdk on session.sandboxName.

04Can an AI SDK sandbox keep its state between runs?

Yes. stop() snapshots the running machine, memory and processes included, and resumeKosa8NetworkSandboxSession({ sandboxId }) restores it under the same name. A template runs expensive setup once and saves it as a kosa8 snapshot that later sessions restore.

In kosa8's docs, a template's second session was ready in 475 ms against 7462 ms for the first. The package also works with HarnessAgent, through createSession({ sandboxSession }) or the provider shape createKosa8Sandbox().

05Other options

  • @ai-sdk/sandbox-vercel. Vercel Sandbox, a hosted option that fits apps already deployed on Vercel.
  • @e2b/ai-sdk-sandbox. E2B's provider for the same interface; E2B's docs describe it as running code in a Firecracker microVM, and it needs an E2B API key.
  • Daytona or Modal. Hosted sandboxes you can call from AI SDK tools over their own SDKs.
  • A Docker container. A custom tool that shells into a container works with any AI SDK version; containers share the host kernel on Linux.

06Sources

Updated 2026-10-31