kosa8 docs

Guides / JavaScript & TypeScript / Choosing a path

JavaScript and TypeScript: choosing a path

There are four ways to use kosa8 from a Node program. Two are npm packages built for it, and two are standard protocols kosa8 speaks. They all reach the same daemon on your machine, so you can mix them. This page explains what each one is for and helps you pick.

How these pages were tested

Every code block in this section was run against a real kosa8 v0.9.10 daemon on an Apple silicon Mac, with the published packages @kosa8/[email protected] and @kosa8/[email protected] on Node.js 25.9.0. The output under each block is what that run printed. The daemon ran in a separate state directory with HOME=/tmp/k8d, so paths in the output read /tmp/k8d/… where yours will show your home folder. Timings are from that run and will differ on your machine. A few things could not be run, such as a GitHub Actions job and a remote worker on another machine. Those are marked untested where they appear.

The four paths

@kosa8/sdkA typed client for kosa8's native API, for Node 18 and later. It covers sandboxes, run and exec, network rules, the credential broker, checkpoints and rewind, fork, explore, snapshots and signed approvals. It has no runtime dependencies. Use it when your own code decides what runs: a backend that runs user code, a test harness, a CI step, or your own agent loop.
@kosa8/ai-sdk-sandboxA kosa8 sandbox for the Vercel AI SDK 7, for Node 22 and later. It implements the AI SDK's sandbox interfaces, so tools get an experimental_sandbox to read and write files and run commands in, and HarnessAgent can use it as its sandbox. Use it when the model decides what runs and you already build on the AI SDK.
MCPkosa8 mcp serve exposes 30 kosa8 tools over the Model Context Protocol, on stdio or HTTP. Any MCP client can use them: the AI SDK's MCP client, Mastra, LangChain.js, Claude Code and others. The model drives kosa8 directly. Use it when you want the agent to create and manage its own sandboxes, inside limits you set on the command line.
Docker APIThe daemon also serves the Docker Engine API on the same socket. dockerode, testcontainers-node and anything else built on them work after you set DOCKER_HOST. Containers run in kosa8's shared engine VM, not in sandboxes of their own. Use it when you already have Docker code and want it off Docker Desktop, unchanged.

Decision table

You want to…@kosa8/sdkAI SDK adapterMCPDocker API
Run code in a microVM with its own kernelyesyesyesno: the shared engine VM
Close the network, or allow named hosts onlyyes, per sandboxyes, networkPolicyyes, per sandboxno
Keep API keys out of the sandbox (broker)yesyes, brokernono
Checkpoint and rewind a running machineyesstop and resume onlyyesno
Fork, and try N approaches in parallelyesnoyesno
Give an AI SDK agent file and shell toolsyou write the toolsyes, built inthe model calls kosa8's toolsno
Let the model create its own sandboxesnonoyesno
Reuse existing dockerode or Testcontainers codenononoyes
Bind-mount host foldersyes, mountsyes, mountsbelow --allow-mountbelow daemon start --allow-mount
Signed approvals for risky actionsyes, approval optionyes, approval settingyes, approval argumentyes (the gate is in front of every route)
Node version18+22+anyany

How they fit together

Four clients, one daemon Your Node program uses one of four clients: @kosa8/sdk, the AI SDK adapter built on it, an MCP client talking to kosa8 mcp serve, or dockerode. All four send HTTP to the kosa8d daemon over its unix socket. The daemon runs sandboxes, each a microVM, for the first three, and runs Docker API containers in its shared engine VM. Your computer @kosa8/sdk ai-sdk-sandbox MCP client dockerode kosa8 mcp serve kosa8d one unix socket: native API and Docker API sandboxes a microVM each, own kernel, own network rule engine VM Docker containers
Every path enters at the same daemon, so every path is identified, gated by policy and written to the audit log the same way.

Packages at a glance

PackageVersionNodeDepends onFormats
@kosa8/sdk0.1.018 or laternothing at run timeESM and CommonJS, with .d.ts
@kosa8/ai-sdk-sandbox0.1.022 or later@kosa8/sdk, @ai-sdk/harness, @ai-sdk/provider-utilsESM and CommonJS, with .d.ts

Both are MIT-licensed. The licence covers the packages only, not kosa8 itself. Source: github.com/kosa8ai/kosa8-js.

What none of them can do yet

Limits in kosa8 v0.9.10 and the 0.1.0 packages

  • A sandbox's network rule is fixed when it is created. There is no call to change egress on a running sandbox. Create a new one with the rule you want.
  • No port forwarding from sandboxes. The native API cannot expose a sandbox port on the host. (The Docker API's -p works, on the shared engine.)
  • Files go in and out through exec. There is no file endpoint for sandboxes. The AI SDK adapter and the helpers on the Files page use sh, cat and base64 inside the container, so the image needs them. Alpine, Debian and the Node images have them.
  • No stdin for exec. A command started with exec cannot read stdin. Use startInteractive and writeStdin for a process that needs input.
  • Checkpoints are built from snapshots on the client side. The daemon has no checkpoint endpoint. The SDK keeps the list in the same file as the CLI, ~/.kosa8/checkpoints.json, so both see the same checkpoints.
  • Remote workers are untested from the SDK. The SDK accepts KOSA8_HOST and KOSA8_TOKEN like the CLI. It was tested over the unix socket and over loopback TCP on one machine, not against a worker on another machine.

Start here

Install and prerequisites kosa8, the daemon, Node, and a first health check. Quickstart Your first sandbox from TypeScript in five steps, each with its output. Vercel AI SDK adapter Give an AI SDK agent a sealed machine for files and commands. Recipes Complete, tested programs for common jobs.