langchain-kosa8
kosa8 Cloud sandboxes as a Deep Agents backend.
Kosa8Sandbox subclasses Deep Agents' BaseSandbox. It implements execute(), upload_files(), download_files(), id and their async variants against the kosa8 Cloud API. BaseSandbox then provides the agent's file tools (ls, read, write, edit, glob, grep) on top of them.
Install
pip install langchain-kosa8
uv add langchain-kosa8
You need a kosa8 Cloud API key. Create one in the kosa8 Cloud dashboard and export it:
export KOSA8_API_KEY=k8c_live_...
Quick start
from langchain_kosa8 import Kosa8Sandbox
backend = Kosa8Sandbox.create() # template "python", key from KOSA8_API_KEY
try:
result = backend.execute("python3 -c 'print(6 * 7)'")
print(result.output, result.exit_code)
finally:
backend.delete_sandbox()
To wrap a sandbox you already started (for example with the kosa8 Python SDK or the dashboard):
backend = Kosa8Sandbox(sandbox_id="sbx_...")
Use with Deep Agents
from langchain_anthropic import ChatAnthropic
from deepagents import create_deep_agent
from langchain_kosa8 import Kosa8Sandbox
backend = Kosa8Sandbox.create(ttl_s=3600) # deleted by kosa8 Cloud after an hour at the latest
agent = create_deep_agent(
model=ChatAnthropic(model="claude-sonnet-4-6"),
system_prompt="You are a coding assistant with sandbox access.",
backend=backend,
)
result = agent.invoke({"messages": [{"role": "user", "content": "Write a hello world Python script and run it"}]})
backend.delete_sandbox()
Async code can use await Kosa8Sandbox.acreate(...), aexecute(), aupload_files(), adownload_files() and adelete_sandbox().
Options
Kosa8Sandbox.create() takes:
| Argument | Default | Meaning |
|---|---|---|
template |
"python" |
Template key (GET /v1/templates lists what your org can use). BaseSandbox's file tools need python3, which the python template has. |
region |
org default | Region id, such as eu-hel1. |
sleep_after_s |
org default | Idle seconds before the sandbox sleeps (0 = never). The next command wakes it. |
ttl_s |
none | Seconds until kosa8 Cloud deletes the sandbox. |
api_key |
KOSA8_API_KEY |
API key. |
base_url |
KOSA8_CLOUD_URL or https://api.kosa8.com |
API address. |
and passes the rest to the constructor:
| Argument | Default | Meaning |
|---|---|---|
timeout |
1800 |
Default command timeout in seconds; 0 means none. Enforced inside the sandbox with timeout -s KILL and by the API's own timeout_s. A timeout answers exit code 124. |
workspace |
/workspace |
Directory commands start in. |
persist_dirs |
("/tmp",) |
Directories outside the workspace kept on the workspace disk, for hosts that start each command in a fresh container (see below). |
shell |
"auto" |
Shell for each command: bash when the image has it, else /bin/sh. |
stream |
None |
None: use streamed exec when the host offers it, else buffered. False: buffered only. True: require streamed exec. |
files_api |
True |
Move files under /workspace through the kosa8 files API; False sends every file through exec. |
Lifecycle helpers: sleep(), wake(), delete_sandbox(), close() (and asleep(), awake(), adelete_sandbox(), aclose()). delete() and adelete() are Deep Agents' file deletes (BaseSandbox runs rm -rf in the sandbox), not the sandbox's.
How it works, and the limits that follow
The package talks to the kosa8 Cloud REST API with httpx: create, exec (buffered and streamed), the files API, sleep, wake and delete.
- State between commands. Commands run in the sandbox's own container, so files written anywhere carry from one command to the next and through sleep and wake. Commands start in
/workspace, so relative paths land there. Shell state (cd, exported variables) does not carry between commands, as with otherBaseSandboxbackends. For hosts that start each command in a fresh container,/tmpis also bind-mounted or linked onto/workspace/.kosa8-persist/tmp(persist_dirs); on a long-lived container this is a no-op after the first command. - Files.
upload_files()anddownload_files()use the kosa8 files API for files under/workspaceof up to 8 MiB. Larger files, files elsewhere, hosts without the files API, and every error (so that Deep Agents'file_not_found,is_directory,permission_deniedandinvalid_pathcodes are exact) go through exec as base64 in chunks: about 36 KB per upload request (the API accepts 64 KiB of JSON per request) and 512 KiB per download request. The image needssh,base64anddd, which the kosa8 templates have. - Long commands. A buffered exec is held to 90 seconds. When the host offers streamed exec (kosa8 Cloud does), every command is streamed and runs to its
timeout. On a host that only buffers, a command past 90 seconds returns exit code124with an explanation. - Output. A buffered exec keeps the first and last 1 MiB of each stream; when output is cut,
truncatedisTrue. A streamed exec keeps all of it. - No stdin, user or port APIs. Commands run as the image's default user. Each exec argument is at most 8 KiB, so commands travel in environment variables, and a command over the 64 KiB request is written to
/workspace/.kosa8-run/and run from there. - grep on Alpine images. busybox
greplacks the-Zflag thatBaseSandbox.grep()uses. The package detects this once per sandbox and searches with a Python 3 script that returns the same results. With GNU grep or ripgrep in the image,BaseSandbox.grep()is used unchanged.
Not covered by this package: kosa8's snapshot, checkpoint, rewind and fork endpoints.
Tests
uv sync --group dev
uv run pytest tests/unit_tests
uv run ruff check . && uv run ruff format --check . && uv run mypy
The unit tests run against an in-process fake of the kosa8 Cloud API (tests/fake_cloud.py) that executes each command for real, with the files API on and off, so they need no network or key.
LangChain's standard SandboxIntegrationTests run two ways:
-
Against the fake API in a local Linux container, which mirrors the
pythontemplate:kosa8 run -d --name k8test python:3.12-alpine sleep 3600 # or: docker run -d ... KOSA8_TEST_CONTAINER=k8test uv run pytest tests/unit_tests/test_standard_local.py # KOSA8_TEST_ENGINE=docker to use docker instead of the kosa8 CLI
-
Against kosa8 Cloud itself (creates one sandbox and deletes it):
KOSA8_API_KEY=k8c_live_... uv run pytest tests/integration_tests
Both runs mark a few standard tests as expected failures, with reasons in tests/standard_overrides.py: langchain-tests 1.1.9 and deepagents 0.7 disagree on glob() paths and on write() to an existing file, which affects every BaseSandbox backend.
License
MIT
Metadata
Release files for langchain-kosa8 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| langchain_kosa8-0.1.0.tar.gz | 36.4 kB | Without provenance | Details for langchain_kosa8-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| langchain_kosa8-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for langchain_kosa8-0.1.0-py3-none-any.whl |
Total release size: 62.3 kB
Release files / langchain_kosa8-0.1.0.tar.gz
| Download URL | langchain_kosa8-0.1.0.tar.gz |
|---|---|
| Size | 36.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8f5a949677b41db8aedaba3433b28ac0d186c7c0fdca8b3ceda6b95c6dbf645d
|
|
BLAKE2b-256 checksum How to use checksums |
02e70c938c5c58d30fa5c18d537a30305ed3a7b92b1fdcd3a11375cfe6a7e5bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Release files / langchain_kosa8-0.1.0-py3-none-any.whl
| Download URL | langchain_kosa8-0.1.0-py3-none-any.whl |
|---|---|
| Size | 25.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
54760f668a1281c0cf1604d18665c4efa5dbdd3d39189f3c41ffef532dd78706
|
|
BLAKE2b-256 checksum How to use checksums |
c74aca1922823d2c4647946a6483c72113cf78e686ed2556d0ca70d2c61f22ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Security for langchain-kosa8 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.