langchain-tenki

In one sentence

langchain-tenki is the bridge that lets an AI agent safely run code and work with files inside a Tenki sandbox.

What is this, in plain language?

Modern AI agents (here, LangChain's "Deep Agents") don't just chat — they can do things: run commands, create files, edit code, search through a project. But you don't want an AI running commands directly on your own computer or server. That would be risky.

A sandbox solves this. Think of it as a clean, disposable computer in the cloud: the AI can do whatever it needs inside that isolated box, and nothing it does can touch your real machine. Tenki is one provider of these sandboxes.

The problem: the AI agent and the Tenki sandbox don't speak the same language. langchain-tenki is the small piece of "glue" (an adapter) that sits between them and translates. When the agent says "run this command" or "save this file," this package passes the request to Tenki, gets the result back, and hands it to the agent in the format it expects.

If you've heard of the official langchain-daytona package, this is the exact same idea — just for Tenki instead of Daytona.

   ┌──────────────┐      ┌───────────────────┐      ┌──────────────────────┐
   │  AI agent    │ ───▶ │   langchain-tenki  │ ───▶ │   Tenki sandbox      │
   │ (Deep Agent) │ ◀─── │   (this package)   │ ◀─── │ (isolated cloud box) │
   └──────────────┘      └───────────────────┘      └──────────────────────┘
        "run a command,        translates the           actually runs the
         read a file…"         request both ways        command / file op

What you need before starting

1. Python 3.11 or newer installed.
2. A Tenki account and an API key. The key is how the package proves it's allowed to use your sandboxes. You provide it through an environment variable called TENKI_API_KEY (more on that below).
3. That's it — installing this package automatically pulls in everything else it depends on (the Tenki SDK and the Deep Agents library).

How to install it

pip install langchain-tenki

How to use it

Here is the smallest complete example. The comments explain each line in plain English:

from tenki_sandbox import Sandbox
from langchain_tenki import TenkiSandbox

# 1. Create a fresh sandbox (a disposable cloud computer).
#    This uses your TENKI_API_KEY from the environment automatically.
sandbox = Sandbox.create()

# 2. Wrap it with this package so an AI agent can use it.
backend = TenkiSandbox(sandbox=sandbox)

# 3. Ask the sandbox to do something, e.g. run a command.
result = backend.execute("echo hello")
print(result.output)   # -> "hello\n"

# 4. When you're finished, shut the sandbox down.
sandbox.terminate()

In a real project you usually don't call backend.execute(...) yourself — you hand backend to a Deep Agent, and the agent decides what to run. This package is what makes that possible.

Setting your API key

The package reads your key from an environment variable. In a terminal:

export TENKI_API_KEY="your-key-here"

(TENKI_AUTH_TOKEN works too.) Never paste your key directly into your code or commit it to git.

How it works (a little more detail)

Everything an agent might want to do comes down to a handful of actions. This package provides three core ones, and builds the rest on top of them for free (the file search/read/edit helpers are inherited from Deep Agents):

What the agent wants	Method	What happens inside Tenki
Run a shell command	execute()	Runs it via bash, returns the text output and exit code.
Put files into the sandbox	upload_files()	Creates folders as needed and writes the files.
Get files out of the sandbox	download_files()	Reads the files back as data.
List / read / search / edit files	inherited helpers	Built automatically on top of the three methods above.

A few sensible behaviors worth knowing:

• Output is the command's normal output (stdout). If a command only prints an error message, that error is returned instead so nothing is lost. To get a command's normal output and its error messages together, add 2>&1 to the command (e.g. my-command 2>&1).
• Errors don't crash your program: if a command times out or the sandbox has a problem, you get a clear result back (with a non-zero status) instead of an exception — timeouts report status 124, other sandbox errors report 1.
• Batches keep going: if you upload or download several files and one fails, the others still succeed and you get a clear per-file status.

Settings you can change

Setting	Default	What it does
sandbox	(required)	The Tenki sandbox you want to use (created with Sandbox.create()).
timeout	1800 (30 min)	How long, in seconds, a command may run before it's stopped — unless you set a per-command timeout.

backend = TenkiSandbox(sandbox=sandbox, timeout=300)  # stop commands after 5 minutes

What's in this repository

Path	What it is
langchain_tenki/sandbox.py	The actual adapter — the heart of the package.
langchain_tenki/__init__.py	Makes TenkiSandbox importable.
tests/unit_tests/	Fast tests that run offline (no Tenki account needed).
tests/integration_tests/	Tests that talk to a real Tenki sandbox (need an API key).
pyproject.toml	Package definition: name, version, dependencies, tooling config.
.github/workflows/	Automation: testing on every change, and publishing releases.
README.md / CHANGELOG.md	This guide, and the history of changes.

For developers

pip install -e ".[test,lint,typing]"
pytest tests/unit_tests -q   # fast, fully mocked, no network
ruff check .                 # lint
ruff format --check .        # formatting
mypy langchain_tenki         # type-check

The integration tests provision a real sandbox and only run when credentials are present:

TENKI_API_KEY=... pytest tests/integration_tests -q

Releases & versioning

langchain-tenki tracks Deep Agents and the tenki-sandbox SDK. Releases are automated; see the CHANGELOG for what changed in each version.

Releases are managed by release-please, which opens a release PR from Conventional Commits. The release-please workflow authenticates with a RELEASE_PLEASE_TOKEN repository secret (a GitHub PAT) rather than the default GITHUB_TOKEN, so that the release PR and tags it creates can trigger CI and the publish workflow. A maintainer must add this secret once: create a classic PAT with the repo scope (or a fine-grained PAT with contents: write and pull-requests: write for this repository) from an account with write access, then save it as the RELEASE_PLEASE_TOKEN secret under Settings → Secrets and variables → Actions.

License

MIT — free to use, modify, and distribute. See LICENSE.