Audience: JavaScript and Python developers who want tested, working code for Tenki Sandbox: disposable Linux VMs for running code and AI agents in isolation. Time: ~10 minutes once you have an API key. That covers cloning, installing one JavaScript example (and optionally one Python example), a run, and a check. Outcome: you've run code in a Tenki sandbox from this repo, confirmed an example works against the live API, and know which example to open next.
Honesty note: every example ships a verify script, but CI doesn't run all of them. It skips
composio-tenki, which needs a Composio API key, andcovalent-tenki, untilcovalent-tenki-plugin0.1.1 is on PyPI.
- A Tenki account and a
tk_API key. Create keys at https://app.tenki.cloud. - Node.js 24 or later. Several
run.mjsdemos, includingrun-code-in-a-sandbox, use top-levelawait using, which Node 22 can't parse. The verify scripts run on Node 20, which is what CI uses. - Python 3.12 and
uvfor the Python examples. They need Python 3.10 or later; CI runs 3.12, and the Covalent example needs your local minor version to match the sandbox's (3.12 on the default image). - Optional: the Tenki CLI, if you'd rather store your key with
tenki loginthan export it in each shell.
git clone https://github.com/LuxorLabs/cookbook.git
cd cookbookEach example is self-contained in its own folder under examples/, with its own README, source code, dependencies, and verify.mjs. There's nothing to install at the root. You install dependencies inside the example you run: npm install for a JavaScript example, or a virtual environment with the example's requirements.txt for a Python one.
Export your key:
export TENKI_AUTH_TOKEN="tk_..."The SDK also reads the key from TENKI_API_KEY, which is the name CI and the Python examples use. Each example's README shows the variable it expects.
To store the key instead, run tenki login --api-key <key>. It writes the key to ~/.config/tenki/config.yaml, and every verify script reads it from there. Some demo scripts, including run-code-in-a-sandbox/run.mjs, read the key only from the environment, so export it before you run those.
You don't need a workspace ID to run these examples. Tenki infers the workspace from the API key. If you set TENKI_WORKSPACE_ID, most scripts pass it along; most verify and agent scripts also read current_workspace_id from ~/.config/tenki/config.yaml. DeerFlow's own provider is an exception: if your account has more than one workspace, it needs workspace_id in the sandbox: block of its config (see its README). Authentication and client setup are covered in the Sandbox SDK guide.
Start with Run code in a sandbox. It covers the whole create, execute, dispose lifecycle in about 15 lines of JavaScript.
cd examples/run-code-in-a-sandbox
npm install
node run.mjsexit 0 -> 42
The script creates a sandbox, runs python3 -c "print(6 * 7)" inside it, prints the exit code and output, and terminates the sandbox when the script ends, because await using disposes it. The sandbox boots in about 2 seconds and is billed per second.
For Python, Run code with Python does the same with the tenki SDK:
cd ../.. # back to the repository root
cd examples/run-code-python
uv venv --python 3.12
uv pip install -r requirements.txt
.venv/bin/python run.pyrun.py prints the same exit 0 -> 42. Unlike run.mjs, it falls back to ~/.config/tenki/config.yaml for the key.
Open the example closest to what you're building and follow its README, which covers setup, the code, and how to check it. The agent framework examples need a model provider key, such as OPENAI_API_KEY, to run the agent. Their verify scripts don't.
| Example | What it covers |
|---|---|
| Run code in a sandbox | Create a sandbox, run a command, dispose it |
| Work with files | Read, write, and list files with the TypeScript SDK |
| Expose a port | Serve a web app on a public preview URL |
| Pause, snapshot, and resume | Preserve a sandbox and pick up where it left off |
| Run code with Python | The official tenki Python SDK |
| Run a full-stack app | Serve an API, frontend, and seeded database from one sandbox |
Give an agent a sandboxed place to run the code it writes.
| Example | Framework |
|---|---|
| Claude Agent SDK | Tenki as the backend for the SDK's bash and file tools |
| Vercel AI SDK | Tenki as the AI SDK's experimental_sandbox |
| LangChain (JavaScript) | Sandboxed code interpreter tool |
| LangChain (Python) | Code-execution tool for a Python agent |
| CrewAI | Run agent-generated code in a sandbox |
| OpenAI Agents SDK | Sandboxed execution as an agent tool |
| LlamaIndex | Sandboxed execution as a FunctionTool |
| Hugging Face smolagents | Remote Python executor for a CodeAgent |
| Pi Durable | Remote execution env — every tool call in a disposable VM |
| AG2 | Native sandbox backend for shell + code tools |
| PraisonAI | One shared sandbox for a whole agent team |
| Example | Integration |
|---|---|
| MCP server | Sandbox tools for Claude, Cursor, or any MCP client |
| MCP Apps | Tools that bring their own UI, rendered in a CopilotKit chat |
| Claude Code | Headless coding agent on a real repo checkout |
| Codex | OpenAI's coding agent, headless, on a real repo checkout |
| OpenCode | Headless OpenCode server on a public preview URL |
| Composio | Tenki tools in a Composio agent |
| Covalent | Each workflow task in its own sandbox |
| AgentBox | Coding-agent boxes as Tenki VMs |
| ComputeSDK | Tenki as a provider for the unified sandbox interface |
| TinyFish | Web agents, fetch, search, and remote browsers from the tenki/tinyfish image |
| Harbor | Agent evals and benchmarks (Terminal-Bench), each trial in its own VM |
| Convex | A sandbox per user from Convex actions, with live state in a Convex table |
Review pull requests with Tenki Code Reviewer.
| Example | What it covers |
|---|---|
| Cursor Origin | Tenki Code Reviewer on Origin pull requests, with AGENTS.md review rules |
Run a self-hosted agent platform's sandboxes on Tenki.
| Example | Platform |
|---|---|
| DeerFlow | Community sandbox provider for ByteDance's SuperAgent harness |
| RAGFlow | Ephemeral sandboxes for the RAG engine's code components |
| Open WebUI | Sandboxed code interpreter for the self-hosted chat platform |
| AgentEnv | Built-in sandbox backend for Scale AI's RL environment framework |
| OpenHermit | Sticky per-agent sandboxes for an agent fleet |
| Omnara | Machine pool provider for the open-source managed agent platform |
Each guide has side-by-side code and an API mapping.
| Guide |
|---|
| E2B to Tenki |
| Modal to Tenki |
| Daytona to Tenki |
Every example ships a verify.mjs script that exercises it against the live API and exits non-zero on any failure, so you can check that it still works before you build on it. CI runs them on every push and pull request, apart from the two skips in the honesty note, and a red build blocks the merge.
If you're still in examples/run-code-in-a-sandbox from Step 3, node verify.mjs is all you need. Otherwise:
cd ../.. # back to the repository root
cd examples/run-code-in-a-sandbox
npm install
node verify.mjs✓ run-code-in-a-sandbox: create → exec python3 → 42 → dispose
That proves your key works and the example's Tenki-facing code runs against the live API: a sandbox boots, runs a command, and returns 42. The script then disposes the sandbox, but it ignores a failed dispose, so the ✓ doesn't prove cleanup. What a verify script doesn't prove: in the agent examples it checks the sandbox tool or backend directly, with no model key, so the agent turn itself isn't tested.
In a Python example, verify.mjs is a shim that runs verify.py with the example's .venv/bin/python if it exists, and otherwise $PYTHON or python3. You can also run .venv/bin/python verify.py yourself.
To check every example at once, run the root script:
cd ../.. # back to the repository root
npm run verifyIt runs each example's verify.mjs in turn and ends with ✓ all examples passed, or with ✗ N example(s) failed and a non-zero exit. It doesn't install anything, so install each example's dependencies first, as CI does in .github/workflows/verify.yml. Unlike CI, it doesn't skip composio-tenki or covalent-tenki; see Troubleshooting.
First-party packages you can install directly in your own project:
| Integration | Install | What it does |
|---|---|---|
| Composio tools | npm install @tenkicloud/composio-tools |
Create, execute, snapshot, and terminate tools for Composio agents |
| Covalent executor | pip install covalent-tenki-plugin |
Runs Covalent workflow tasks in Tenki sandboxes |
| GitHub Actions | uses: TenkiCloud/actions/setup-cli@v1 |
Installs the Tenki CLI and builds sandbox templates in CI |
| Go SDK | go get github.com/LuxorLabs/tenki-sdk-go/sandbox |
Go client for the Tenki Sandbox API |
| Convex component | npm install @tenkicloud/convex |
Creates and drives sandboxes from Convex actions, with each one's state in a Convex table |
Covalent note: covalent-tenki-plugin 0.1.0, the only release on PyPI, depends on the renamed tenki-sandbox package and doesn't install. Wait for 0.1.1.
These open-source projects ship a Tenki provider or backend out of the box:
| Project | Tenki integration |
|---|---|
| RAGFlow | Sandbox provider for the RAG engine's code executor — example |
| DeerFlow | Sandbox provider for ByteDance's SuperAgent harness — example |
| AgentBox | Provider for running parallel agents in sandboxed VMs — example |
| ComputeSDK | Tenki provider for the multi-provider compute toolkit — example |
| AgentEnv Framework | Sandbox backend for Scale AI's RL environments — example |
| OpenHermit | Sandboxed exec backend for AI agent fleets — example |
| Omnara | Machine pool provider for the open-source managed agent platform — example |
- ❌
missing auth token - set TENKI_AUTH_TOKEN or TENKI_API_KEY or use authToken option. The SDK found no key.run.mjsreads it from the environment only, not from~/.config/tenki/config.yaml. ExportTENKI_AUTH_TOKENorTENKI_API_KEYin the shell you run it from. - ❌
invalid auth token - API keys and service tokens must start with tk_. The SDK accepts onlytk_API keys. Create one at https://app.tenki.cloud. - ❌
No token. Set TENKI_AUTH_TOKEN, or run `tenki login`.from a JavaScript example'sverify.mjs(composio-tenkiandvercel-ai-sdkprintNo Tenki token. …instead, andmcp-tenki-sandboxprintsNo token. Set TENKI_API_KEY, …), orNo API key. Set TENKI_API_KEY, or run `tenki login --api-key <key>`.from a Python example'sverify.py. A verify script found no key inTENKI_AUTH_TOKEN,TENKI_API_KEY, or~/.config/tenki/config.yaml. Export one of the variables, or runtenki login --api-key <key>. - ❌
node run.mjsfails with aSyntaxErroratawait using. Top-levelawait usingneeds Node 24, and Node 22 can't parse it. Switch to Node 24 or newer.node verify.mjsstill runs on Node 20. - ❌
npm run verifyprintsFAILED: <example>for examples you haven't set up. The script assumes every example's dependencies are already installed. Install them in each example's folder first, or runnode verify.mjsin the one example you care about. - ❌
FAILED: composio-tenkiorFAILED: covalent-tenkiin a localnpm run verify. CI skips both.composio-tenkialso needs aCOMPOSIO_API_KEYfrom https://app.composio.dev.covalent-tenkineedscovalent-tenki-plugin0.1.1 or later, because 0.1.0 declares the renamedtenki-sandboxpackage and no longer installs. There's no fix forcovalent-tenkiuntil 0.1.1 is published. Ignore that failure locally, as CI does, or runnode verify.mjsonly in the examples you use. - ❌
ModuleNotFoundError: No module named '<package>'from a Python example'sverify.mjs. The shim runs the example's.venv/bin/pythonif it exists, and otherwise$PYTHONorpython3, so it can't see packages installed into another interpreter. Create the venv in the example's folder withuv venv --python 3.12anduv pip install -r requirements.txt. Without a venv, you can instead setPYTHONto the interpreter that has them.
When shouldn't I use this? When you want a library rather than a demo. Each example is short and shows one thing, so it's meant to be read and copied, not added as a dependency. To put Tenki in your own project, install the SDK or one of the official integrations above (see the Covalent note). And don't read a passing verify script as proof that an agent example's model turn works: it checks only the Tenki-facing part.
Which example should I copy for my own integration? For direct SDK use, run-code-in-a-sandbox. For a framework agent with a code-execution tool, langchain-code-interpreter. For a pluggable sandbox backend for a framework, vercel-ai-sdk.
Do the examples clean up their sandboxes? Sandboxes are billed per second, so it matters. The two first-run scripts do: run.mjs disposes its sandbox with await using, and run.py with a with block. Every verify script is required to clean up any sandbox it creates.
Contributions are welcome. CONTRIBUTING.md covers local setup, the example checklist, and the verification contract. Every new example ships a verify.mjs that CI runs against the live API, and adds a row to one of the tables above.