Skip to main content

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 other BaseSandbox backends. For hosts that start each command in a fresh container, /tmp is 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() and download_files() use the kosa8 files API for files under /workspace of 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_denied and invalid_path codes 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 needs sh, base64 and dd, 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 code 124 with an explanation.
  • Output. A buffered exec keeps the first and last 1 MiB of each stream; when output is cut, truncated is True. 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 grep lacks the -Z flag that BaseSandbox.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.

The Kosa8Sandbox backend does not use kosa8's snapshot, checkpoint, rewind or fork endpoints. The bundled client has methods for most of them if you want to call them yourself (see below).

The bundled client and its errors

langchain_kosa8.Kosa8Client and AsyncKosa8Client cover more of the sandbox API than the backend needs: update_sandbox (PATCH lifetime and sleep timer, or clear_lifetime=True), list_sandboxes / iter_sandboxes (limit / cursor paging), list_files, create_checkpoint, list_checkpoints, rewind_sandbox and fork_sandbox. create_sandbox checks ttl_s (60 s to 90 days) before sending, and also takes delete_after (Unix ms or ISO 8601). Hosts without the data plane answer 501 to the checkpoint, rewind and fork calls.

Errors are typed. All are Kosa8Error, with status, code and the decoded body:

Error When
Kosa8PaymentRequiredError 402: no payment method, or the spending cap is reached. Show upgrade_url; an agent should relay agent_message and stop.
Kosa8OrgFrozenError 423 org_frozen: an owner or admin must unfreeze the org.
Kosa8RateLimitError 429, including quota_exceeded; retry_after is in seconds.
Kosa8ExecTimeoutError An exec cut off by the API's time limit (also a Kosa8TimeoutError).
Kosa8NotSupportedError 501: the host cannot do this yet.

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 python template:

    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.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for langchain-kosa8 0.2.0
File Size Uploaded Provenance Actions
langchain_kosa8-0.2.0.tar.gz 41.6 kB Without provenance Details for langchain_kosa8-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for langchain-kosa8 0.2.0
File Interpreter ABI Platform Actions
langchain_kosa8-0.2.0-py3-none-any.whl Python 3 none any Details for langchain_kosa8-0.2.0-py3-none-any.whl

Total release size: 70.8 kB

Release files / langchain_kosa8-0.2.0.tar.gz

Download URL langchain_kosa8-0.2.0.tar.gz
Size 41.6 kB
Tags Source
SHA-256 checksum
How to use checksums
e8e991c2f53db307ca974cb9c47e0476bb45f063a6ad781250d269bc47e38dc2
BLAKE2b-256 checksum
How to use checksums
d5e35e74b92736b1f66cfa9c98863d1408bae48f7d671285184c3a15fda44d0b
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.2.0-py3-none-any.whl

Download URL langchain_kosa8-0.2.0-py3-none-any.whl
Size 29.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3ca153af1b5e3eca277f1480fffcecf24a01ec66167f88a5239fc10196c1b0a1
BLAKE2b-256 checksum
How to use checksums
05d6e3110ffc9266f6f0d99b8c7902454068a54c9f4ea9de1546cc721a67c0c4
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.2.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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page