Guides / kosa8 Cloud / Framework integrations
Framework integrations
Agent frameworks and eval harnesses have their own sandbox interface. kosa8 Cloud
plugs into each one as a provider, so an agent or an eval moves onto kosa8 microVMs without being
rewritten. Each plugin uses the kosa8 Cloud API with your KOSA8_API_KEY, so the same limits,
egress policy, billing and audit log apply as for a direct API call.
| Framework | Package | What it plugs into |
|---|---|---|
| OpenAI Agents SDK | openai-agents-kosa8 | Sandbox agents' BaseSandboxClient (agents.sandbox) |
| Harbor (Terminal-Bench) | harbor-kosa8 | A Harbor environment: -e harbor_kosa8:Kosa8Environment |
| Inspect AI | inspect-kosa8 | The kosa8 sandbox type: sandbox="kosa8" |
| LangChain Deep Agents | langchain-kosa8 | A Deep Agents BaseSandbox backend |
| Code written for E2B | none | The E2B-compatible API at https://api.kosa8.com/e2b |
To give an agent sandbox tools rather than a sandbox backend, see OpenAI Agents SDK and LangChain in the Python guides.
OpenAI Agents SDK
pip install openai-agents-kosa8 export KOSA8_API_KEY=k8c_live_…
from agents import RunConfig, Runner
from agents.sandbox import SandboxAgent, SandboxRunConfig
from agents_kosa8 import Kosa8SandboxClient, Kosa8SandboxClientOptions
agent = SandboxAgent(name="coder", instructions="Fix the failing test.")
options = Kosa8SandboxClientOptions(size="2x4", egress={"presets": ["pypi", "github"]})
result = await Runner.run(agent, "Run the tests and fix what fails.",
run_config=RunConfig(sandbox=SandboxRunConfig(client=Kosa8SandboxClient(), options=options)))
- Each session is a persistent kosa8 sandbox, so files and background processes last
between commands. Commands run in the manifest root, which is
/workspaceby default. - Options carry the create fields:
template,image,size,disk_gb,region,ttl_s,sleep_after_s,egress,secrets.env_varsgo with every command. - Workspace persistence and hydration use the SDK's tar format. A hydrated archive goes through the files API, so it can be at most 100 MB.
- An exposed port becomes a kosa8 preview URL. It is private
unless you set
public_ports=True. - On shutdown the sandbox is deleted. With
pause_on_exit=Trueit sleeps instead, andresumewakes it. If it is gone,resumecreates a new one with the same settings. - No PTY sessions. The package is built against
openai-agents0.24 and pinned to that minor version, because the SDK's sandbox interface is still changing.
Harbor
uv tool install harbor --with harbor-kosa8 harbor run -d terminal-bench@2.0 -a claude-code -m anthropic/claude-sonnet-4-6 \ -e harbor_kosa8:Kosa8Environment -n 8
Pass options with --ek key=value, for example --ek template=node. See the
harbor-kosa8 README.
Inspect AI
pip install inspect-kosa8 inspect eval ctf.py --sandbox kosa8
The package registers the kosa8 sandbox type through Inspect's entry point, so
Task(..., sandbox="kosa8") needs no extra import. See the
inspect-kosa8 README.
LangChain Deep Agents
from deepagents import create_deep_agent from langchain_kosa8 import Kosa8Sandbox backend = Kosa8Sandbox.create(ttl_s=3600) agent = create_deep_agent(model="anthropic:claude-sonnet-4-6", backend=backend)
See the langchain-kosa8 README.
Code written for E2B
kosa8 Cloud answers a subset of E2B's API. Code that uses the E2B SDK runs on kosa8 when you change three environment variables, with no code changes:
export E2B_API_KEY=k8c_live_… # a kosa8 Cloud API key export E2B_API_URL=https://api.kosa8.com/e2b export E2B_SANDBOX_URL=https://api.kosa8.com/e2b/envd
from e2b import Sandbox
sbx = Sandbox.create(timeout=300) # a kosa8 sandbox, deleted after 300 s
sbx.files.write("hello.py", "print(1)\n") # /workspace/hello.py
print(sbx.commands.run("python3 hello.py").stdout)
sbx.kill()
Each E2B call is translated into the kosa8 API call that does the same thing, and it is checked,
limited, billed and audited like that call. A sandbox you create this way is an ordinary kosa8 sandbox,
so it shows in the dashboard and works with every other kosa8 call. Relative file paths resolve under
/workspace. A command runs under bash -l, or sh where the image has no bash.
Supported
| E2B SDK | kosa8 Cloud |
|---|---|
Sandbox.create(template, timeout, auto_pause, allow_internet_access) | Create. template is a kosa8 template name (base is the default), timeout becomes ttl_s, auto_pause becomes sleep_after_s, and allow_internet_access=False becomes egress: {internet: false}. |
Sandbox.list(query=state) | List; paused is a sleeping sandbox. |
Sandbox.get_info, kill, set_timeout | Get, delete, PATCH ttl_s. |
pause, connect / resume | Sleep and wake. |
files.read, files.write | The files API, streamed (100 MB a request through the API). |
commands.run(cmd, envs, cwd, timeout) | Streamed exec; stdout, stderr and the exit code come back as they happen, and on_stdout / on_stderr callbacks work. |
Not supported
These answer 501 (or Connect unimplemented), so code fails loudly rather than quietly doing
something else:
envsonSandbox.create(pass them tocommands.run),metadataon create or as a list filter, and custom CPU or memory (use a kosa8sizethrough the native API).- PTY,
commands.send_stdin,commands.kill,commands.list,commands.connect, and background commands. files.list,exists,get_info,make_dir,remove,renameandwatch_dir. Run the shell equivalent withcommands.run.- Metrics, snapshots, network updates, volumes, MCP gateways and the template build API.
The mode was tested with the E2B Python SDK 2.64.0. E2B plans to drop E2B_API_URL and
E2B_SANDBOX_URL in its next major version, so pin e2b<3.