# 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`](https://github.com/kosa8ai/harbor-kosa8) | A Harbor environment: `-e harbor_kosa8:Kosa8Environment` |
| Inspect AI | [`inspect-kosa8`](https://github.com/kosa8ai/inspect-kosa8) | The `kosa8` sandbox type: `sandbox="kosa8"` |
| LangChain Deep Agents | [`langchain-kosa8`](https://github.com/kosa8ai/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](https://docs.kosa8.com/guides/py-frameworks/) 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 `/workspace` by default.

- Options carry the create fields: `template`, `image`, `size`, `disk_gb`, `region`, `ttl_s`, `sleep_after_s`, `egress`, `secrets`. `env_vars` go 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](https://docs.kosa8.com/guides/cloud-previews/). It is private unless you set `public_ports=True`.

- On shutdown the sandbox is deleted. With `pause_on_exit=True` it sleeps instead, and `resume` wakes it. If it is gone, `resume` creates a new one with the same settings.

- No PTY sessions. The package is built against `openai-agents` 0.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](https://github.com/kosa8ai/harbor-kosa8).

## 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](https://github.com/kosa8ai/inspect-kosa8).

## 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](https://github.com/kosa8ai/langchain-kosa8).

## 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:

- `envs` on `Sandbox.create` (pass them to `commands.run`), `metadata` on create or as a list filter, and custom CPU or memory (use a kosa8 `size` through the native API).

- PTY, `commands.send_stdin`, `commands.kill`, `commands.list`, `commands.connect`, and background commands.

- `files.list`, `exists`, `get_info`, `make_dir`, `remove`, `rename` and `watch_dir`. Run the shell equivalent with `commands.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`.

---
Source: https://docs.kosa8.com/guides/cloud-integrations-frameworks/
