langchain-lightning

Lightning AI sandbox integration for Deep Agents.

Quick Install

pip install langchain-lightning

Deep Agents SDK

from lightning_sdk.sandbox import Sandbox
from langchain_lightning import LightningSandbox, ensure_workdir

# python313 ships python3, which Deep Agents file tools require.
sandbox = Sandbox.create(
    instance_type="cpu-1",
    runtime="python313",
    persistent=True,  # optional: stop/resume by id across runs
)
ensure_workdir(sandbox, "/root")
backend = LightningSandbox(sandbox=sandbox)

try:
    result = backend.execute("python3 --version && echo hello")
    print(result.output)
finally:
    sandbox.delete()

Reconnect to a durable sandbox (auto-resumes when paused):

from lightning_sdk.sandbox import Sandbox
from langchain_lightning import LightningSandbox, ensure_workdir, resume_if_needed

sandbox = resume_if_needed(Sandbox().get("sbx_..."))
ensure_workdir(sandbox, "/root")
backend = LightningSandbox(sandbox=sandbox)

The backend also works with async Deep Agents via the inherited aexecute, aupload_files, adownload_files, and related methods (the Lightning SDK is synchronous, so these run on a worker thread).

Deep Agents Code

Install langchain-lightning into the dcode environment, then run with the Lightning sandbox provider:

dcode --install langchain-lightning --package
export LIGHTNING_API_KEY=...
dcode --sandbox lightning

The provider defaults:

Setting	Default
runtime	python313 (has python3)
instance type	cpu-1
sandbox lifetime	30 minutes
workdir	/root
persistent	false

Optional env vars: LIGHTNING_SANDBOX_RUNTIME, LIGHTNING_SANDBOX_IMAGE, LIGHTNING_SANDBOX_INSTANCE_TYPE, LIGHTNING_SANDBOX_TIMEOUT (seconds), LIGHTNING_SANDBOX_PERSISTENT, LIGHTNING_SANDBOX_NETWORK_POLICY, LIGHTNING_CLOUD_URL.

When reconnecting by sandbox id, the provider resumes paused/stopped persistent sandboxes and ensures the workdir exists.

What is this?

langchain-lightning adapts an existing Lightning AI sandbox to the Deep Agents sandbox protocol. It implements the execute, upload_files, and download_files primitives over the lightning_sdk.sandbox SDK; Deep Agents derives the rest of the filesystem operations (ls, read, write, edit, grep, glob) from those.

Commands run detached and are awaited so per-command timeouts are honored. File transfer is bridged through base64 so arbitrary binary content round-trips losslessly despite Lightning's text-based file API.

For SDK use, this package intentionally does not hide Lightning sandbox lifecycle management. Use the Lightning SDK to create, connect to, configure, and delete sandboxes, then pass the sandbox object to LightningSandbox.

For Deep Agents Code, the package also exposes a dcode sandbox provider entry point. The provider creates, reconnects to, and deletes Lightning sandboxes for dcode --sandbox lightning.

Note

Deep Agents runs its file operations with python3 inside the sandbox, so create sandboxes with a runtime that ships a Python interpreter (e.g. runtime="python313", the default for the provider). The bare default CPU image does not include Python.

Contributing

Contributions are welcome. Keep the adapter focused on implementing the Deep Agents sandbox backend protocol over the official Lightning SDK.

Development

uv sync --group test
make test
make lint

Integration tests require LIGHTNING_API_KEY and hit the real Lightning API (create / shell / files / pause-resume):

export LIGHTNING_API_KEY=...
make integration_tests

CI runs unit tests on every PR and live integration tests when the LIGHTNING_API_KEY repository secret is available (same-repo PRs, pushes to main, nightly schedule, and manual workflow_dispatch).