Guides
Start here. Each one is a walkthrough you can follow end to end on your own machine, or an explanation with the picture.
Getting started
Install kosa8One line in a terminal, or the Mac app. Both take about a minute.
Your first sandboxMake a sealed machine, run something inside it, and see why it is not just a container.
kosa8 CloudRun kosa8 sandboxes and functions on our hosts: sign up at cloud.kosa8.com, add a payment method, make an API key, and call it from the SDKs or plain HTTP.
Save and undoCheckpoint before something risky, rewind after it goes wrong. About a second either way.
Try several ideas at onceFork a machine per idea, run them in parallel, and let kosa8 report which worked.
The Mac appA window onto every machine, container and save point — including the tree of what came from what.
Local modelsRun AI on your own machine. Nothing sent out, nothing charged per word.
When something is wrongkosa8 doctor finds it, explains why it matters, and repairs what is safe to repair.
AI agents
Connect Claude, Cursor or CodexGive your AI coding agent kosa8 sandboxes in two commands: kosa8 mcp install adds the tools, kosa8 skill install teaches the agent when to use them.
Run an AI assistantClaude Code, Codex, Gemini and others, each in a sealed machine that can only reach what you allow — and never holds your API key.
Securing an agentEverything kosa8 does to secure an AI agent itself, not only the sandbox around it: the layers, the threats each one answers, and what none of them do.
Keep API keys out of the sandboxHow kosa8's egress broker lets an AI agent use an API key it never holds: the sandbox gets a placeholder, and the real key is added on your computer.
Network rulesWhat a kosa8 sandbox can reach, how to say so, and where it is enforced: the guard on your computer, DNS answered on the host, and the egress broker on top.
Tool servers (MCP)Run third-party MCP servers behind kosa8's gateway: each in its own sandbox, with pinned tool definitions and checked arguments.
Rules for tool callsDecide an AI agent's tool call by its arguments: allow it, deny it, or hold it until a person approves that exact call.
Agent identityGive each AI agent a token the service verifies, so policy can differ between agents and the audit log names which one acted.
Writing a kitDescribe the environment an agent runs in: its image, what is installed, the one folder it sees, the hosts it reaches and the keys it uses.
Agent troubleshootingEvery refusal and warning an agent or its user can meet, what each one means and what to do about it.
SDKs
SDKs in five languagesDrive kosa8 from Python, TypeScript, Go, Ruby or Java. What the SDKs do in plain words, how to install each, and which page to read next.
Native HTTP APIThe kosa8 daemon's /kosa8/v1 API that every SDK is built on: transport, headers, streaming frames, errors, and each sandbox, process, snapshot and fork endpoint with its request and response.
Python
Python quickstartRun code in a sealed microVM sandbox from Python in five minutes: install the kosa8 package with pip or uv, connect to the daemon, create a sandbox with no network, run a command, checkpoint, rewind and delete. Every step with its real output.
Python developer guideEverything the kosa8 Python SDK does, in depth: connecting (socket, KOSA8_HOST, tokens, timeouts), sandboxes and egress, run, exec, stdin and attach, snapshots, fork, explore, checkpoints and the shared checkpoints.json, threads and asyncio, and patterns for AI agent loops. Tested against kosa8 0.9.36.
Python: OpenAI Agents SDK and LangChainGive an OpenAI Agents SDK or LangChain/LangGraph agent a kosa8 sandbox as tools: run code, a shell that keeps cd, files, git and preview links, with errors handed back to the model as text.
Python: RL rollouts and evalsUse kosa8 sandboxes for reinforcement learning and evals in Python: one sealed environment per episode, fork a prepared state into many, checkpoint and rewind mid-episode, score by running tests, and clean up with ephemeral sandboxes.
Python errors and troubleshootingEvery exception the kosa8 Python SDK (0.1.1) raises: when it is raised, its attributes, a real message from kosa8 0.9.36, and what to do. Plus a troubleshooting table of symptoms, causes and fixes: daemon not running, socket paths, names in use, timeouts, stdin, failed rewinds, checkpoint races and pip on macOS.
Python API referenceEvery public class, function, method, constant and dataclass of the kosa8 Python SDK 0.1.1: exact signatures, parameters, defaults, return shapes, endpoints and errors.
Go
Go quickstartRun code in a sealed microVM sandbox from Go in five minutes: install kosa8-go, connect to the daemon, create a sandbox with no network, run a command, checkpoint, rewind and delete. Every step with its real output.
Go developer guideEverything kosa8-go v0.1.2 can do, explained in plain words first and then in depth: connecting, contexts and timeouts, goroutine safety, sandboxes, running code, streaming and stdin, checkpoints shared with the CLI, snapshots, fork and explore, and tested recipes.
Go errors and troubleshootingEvery error kosa8-go v0.1.2 returns: the Error type and its Kind, errors.Is and errors.As usage, when each kind happens with real messages from kosa8 0.9.36, how to handle it, and a symptom-to-fix troubleshooting table.
Go API referenceEvery exported type, field, function, method and constant of github.com/kosa8ai/kosa8-go v0.1.2, with exact signatures, the HTTP calls each method makes, what it returns and how it fails.
Ruby
Ruby quickstartRun code in a sealed microVM sandbox from Ruby in five minutes: install the kosa8 gem, connect to the daemon, create a sandbox with no network, run a command, checkpoint, rewind and delete. Every step with its real output.
Ruby developer guideEverything the kosa8 Ruby gem does, explained simply and then in depth: sandboxes, network rules, run, exec, stdin and attach, snapshots, fork, explore, checkpoints shared with the CLI, environment variables, threads, timeouts, and recipes for agent loops and clean-up.
Ruby errors and troubleshootingEvery exception the kosa8 Ruby gem 0.1.2 raises: the class hierarchy, when each is raised, its fields, a real message from kosa8 0.9.36, and how to handle it. Then a troubleshooting table from symptom to cause to fix.
Ruby API referenceEvery public class, method, keyword argument, default, return value and exception of the kosa8 Ruby gem 0.1.2, with the HTTP call each method makes, copied from the source.
Java
Java quickstartRun code in a sealed microVM sandbox from Java in five minutes: add com.kosa8:kosa8 0.1.2 with Maven or Gradle, connect to the daemon, create a sandbox with no network, run a command, checkpoint, rewind and delete. Every step with its real output.
Java developer guideEverything the kosa8 Java SDK does, in plain words first and then in depth: connecting locally or to a remote worker, sandboxes and network rules, run, exec, stdin and attach, streaming and timeouts, snapshots, fork and explore, checkpoints shared with the CLI, thread safety, and tested recipes.
Java errors and troubleshootingEvery exception the kosa8 Java SDK throws: the class hierarchy, checked or unchecked, when each is thrown, its fields, real messages from kosa8 0.9.36, and a troubleshooting table from symptom to cause to fix.
Java API referenceEvery public class, constructor, method, builder option and record of com.kosa8:kosa8 0.1.2, with exact signatures, defaults, the HTTP calls each method makes, what it returns and what it throws.
JavaScript & TypeScript
JavaScript and TypeScript: choosing a pathFour ways to drive kosa8 from Node: the @kosa8/sdk client, the Vercel AI SDK adapter, MCP, and the Docker API. What each is for, with a decision table.
Install and prerequisites (JavaScript)Install kosa8 and start its daemon, install @kosa8/sdk or @kosa8/ai-sdk-sandbox, check the connection with health() and version(), and set up TypeScript.
Quickstart (@kosa8/sdk)Your first kosa8 sandbox from Node in five steps: connect, create a sealed microVM, run a command, exec into a container, then checkpoint and rewind. Each step with its real output.
Connecting (JavaScript)How @kosa8/sdk finds the daemon: the default socket, socketPath, KOSA8_HOST forms, KOSA8_TOKEN, KOSA8_INSECURE, the actor and agent-token headers, and remote workers.
Sandboxes (JavaScript)Create kosa8 sandboxes from Node with cpus, memory, disk, mounts, labels, packet capture and a broker; list, get, stop, start, delete and wipe them; manage their images and containers.
Network and secrets (JavaScript)Set a kosa8 sandbox's egress from Node: deny, any, fakenet or an allow-list; read what was refused; and use the credential broker so the agent never holds an API key.
Running code (JavaScript)run, exec, execFrames, startContainer, startInteractive, writeStdin and attach in @kosa8/sdk: streaming output, exit codes as results, stdin, time limits and stream errors.
Files (JavaScript)Get files into and out of a kosa8 sandbox from Node: through exec with base64, through a host folder mount, or with the AI SDK adapter's read and write methods.
Checkpoints and rewind (JavaScript)Save a running kosa8 sandbox before a risky step and put it back in about half a second, processes and all, from Node. How checkpoints are stored and shared with the CLI.
Fork and explore (JavaScript)Copy a running kosa8 sandbox into live, independent copies from Node, and run several approaches in parallel to keep the fastest one that works (best-of-N).
Snapshots (JavaScript)Save a running kosa8 sandbox as a named snapshot from Node, restore it as many times as you like, encrypt it, and restore a sealed snapshot whose seal does not verify.
Approvals and policy (JavaScript)When an org policy wants named people to approve an action, @kosa8/sdk throws Kosa8ApprovalRequiredError. How a human approves through the CLI, and how your code repeats the call with the approval id.
Errors reference (JavaScript)Every error class @kosa8/sdk throws: when it is thrown, its fields, a real message from kosa8 v0.9.10, and how to handle it.
Vercel AI SDK 7 adapter@kosa8/ai-sdk-sandbox: run an AI SDK agent's files and commands in a kosa8 microVM. Sessions, the work container, restricted(), templates, network policy, stop and resume, destroy, and a full generateText agent.
Recipes (JavaScript)Complete, tested Node programs for kosa8: run LLM-generated code safely, a coding agent on a mounted repo, parallel test variants, checkpoint before a migration, an Express or Next.js route, CI, MCP from TypeScript frameworks, and dockerode or Testcontainers.
API reference (JavaScript)Every exported function, class, type and option of @kosa8/sdk 0.1.0 and @kosa8/ai-sdk-sandbox 0.1.0, checked against their .d.ts files.
Troubleshooting (JavaScript)Problems you can meet driving kosa8 from Node, with the real messages: daemon not running, socket path length on macOS, a locked Mac, disk space, Node versions, egress refusals, approvals, and a script that does not exit.
Company and audit
Company rulesSigned policy that a laptop cannot edit its way around, and a record of every decision.
Policy referenceEvery field of the two signed policy documents, where each is enforced, and what happens when a policy is missing or edited.
The audit logWhat kosa8 writes down about every action, how to read it, and how to prove nobody edited it.