Tenki cookbook

Runnable examples for Tenki Sandbox. Each folder under examples/ is a short program you can run against the live API and copy into your own project.

The first example takes about 10 minutes once you have an API key.

You need:

• A Tenki account and a tk_ API key. Create keys at app.tenki.cloud.
• Node.js 24 or later for the JavaScript demos. Several run.mjs scripts, including the first example, use top-level await using, which Node 22 cannot parse. The verify scripts run on Node 20, which is what CI uses.
• Python 3.12 and uv for the Python examples. They run on Python 3.10 or later. CI uses 3.12. The Covalent example needs your local minor version to match the sandbox image (3.12 on the default image).
• Optional: the Tenki CLI, if you want tenki login to store the key.

git clone https://github.com/LuxorLabs/cookbook.git
cd cookbook

Each example is self-contained: its own README, source, and dependencies. Nothing installs at the repository root. Install dependencies inside the example you run, with npm install or a virtual environment and that folder's requirements.txt.

export TENKI_API_KEY="tk_..."

The JavaScript SDK also reads TENKI_AUTH_TOKEN. Python examples and CI use TENKI_API_KEY. Each example README names the variable it expects.

To store the key, run tenki login --api-key <key>. That writes ~/.config/tenki/config.yaml, and every verify script reads it from there. Some demos, including examples/run-code-in-a-sandbox/run.mjs, read the environment only, so export the key before you run those.

Tenki infers the workspace from the API key. If you set TENKI_WORKSPACE_ID, most scripts pass it through. Most verify and agent scripts also read current_workspace_id from ~/.config/tenki/config.yaml. DeerFlow's provider is the exception: when the account has more than one workspace, set workspace_id in the sandbox: block of its config (DeerFlow example). Authentication and client setup are in the Sandbox SDK guide.

Start with Run code in a sandbox. It is the create, execute, and dispose lifecycle in about 15 lines of JavaScript.

cd examples/run-code-in-a-sandbox
npm install
node run.mjs

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

The same loop in Python is Run code with Python. From the repository root:

cd examples/run-code-python
uv venv --python 3.12
uv pip install -r requirements.txt
.venv/bin/python run.py

run.py prints exit 0 -> 42. It also accepts a key saved by tenki login.

Open the example closest to what you are building and follow its README. Agent-framework examples need a model provider key, such as OPENAI_API_KEY, to run the agent. Their verify scripts call the sandbox tool directly and do not need that key.

Give an agent a sandbox to run the code it writes.

Review pull requests with Tenki Code Reviewer.

Run a self-hosted agent platform's sandboxes on Tenki.

Each guide shows the two APIs side by side.

Every example includes verify.mjs. It calls the live API and exits non-zero when a check fails.

cd examples/run-code-in-a-sandbox
npm install
node verify.mjs

✓ run-code-in-a-sandbox: create → exec python3 → 42 → dispose

That line means your key works: a sandbox boots, runs a command, and returns 42. Verify scripts still exit 0 if the final dispose fails, so the check mark is about the command result. In an agent example, the script checks the sandbox tool or backend and does not run a model turn.

In a Python example, verify.mjs is a shim. It runs verify.py with the example's .venv/bin/python when that interpreter exists, and otherwise with $PYTHON or python3. You can also run .venv/bin/python verify.py yourself.

To check every example, from the repository root:

node verify.mjs

It runs each example's verify.mjs and ends with ✓ all examples passed, or with ✗ N example(s) failed and a non-zero exit. It does not install dependencies. Install them first, as CI does in .github/workflows/verify.yml.

CI runs the same checks on every push and pull request, and a failed check blocks the merge. Two examples are skipped in CI:

• composio-tenki, which needs a Composio API key
• covalent-tenki, until covalent-tenki-plugin 0.1.1 is on PyPI

node verify.mjs on your machine runs those two as well. If they fail locally, see Troubleshooting.

Packages you install in your own project:

covalent-tenki-plugin 0.1.0 is the only release on PyPI. It depends on the renamed tenki-sandbox package, so pip install fails until 0.1.1 is published.

These projects ship a Tenki provider or backend:

• missing auth token - set TENKI_AUTH_TOKEN or TENKI_API_KEY or use authToken option. The SDK found no key. run.mjs reads the environment only. Export TENKI_AUTH_TOKEN or TENKI_API_KEY in the shell you run it from.
• invalid auth token - API keys and service tokens must start with tk_. The SDK accepts tk_ API keys. Create one at app.tenki.cloud.
• No token. Set TENKI_AUTH_TOKEN, or run tenki login. A JavaScript verify.mjs found no key in TENKI_AUTH_TOKEN, TENKI_API_KEY, or ~/.config/tenki/config.yaml. composio-tenki and vercel-ai-sdk print No Tenki token. …. mcp-tenki-sandbox prints No token. Set TENKI_API_KEY, …. Export one of the variables, or run tenki login --api-key <key>.
• No API key. Set TENKI_API_KEY, or run tenki login --api-key <key>. A Python verify.py found no key in those same places. Export TENKI_API_KEY, or run tenki login --api-key <key>.
• node run.mjs fails with a SyntaxError at await using. Top-level await using needs Node 24. Node 22 cannot parse it. node verify.mjs still runs on Node 20.
• node verify.mjs at the repository root prints FAILED: <example> for an example you have not set up. The root script expects that example's dependencies to be installed already. Install them in the example folder, or run that folder's own node verify.mjs.
• FAILED: composio-tenki or FAILED: covalent-tenki from node verify.mjs at the repository root. CI skips both. composio-tenki also needs a COMPOSIO_API_KEY from app.composio.dev. covalent-tenki needs covalent-tenki-plugin 0.1.1 or later, because 0.1.0 depends on the renamed tenki-sandbox package and no longer installs. Until 0.1.1 is published, run node verify.mjs inside the examples you use.
• ModuleNotFoundError: No module named '<package>' from a Python example's verify.mjs. The shim runs .venv/bin/python when that file exists, and otherwise $PYTHON or python3. Create the venv in the example folder with uv venv --python 3.12 and uv pip install -r requirements.txt. You can also set PYTHON to an interpreter that already has the packages.

Can I depend on this repository from an app? Each example is a short program to read and copy. To use Tenki in a project you ship, install the SDK or one of the official integrations above. A passing verify script checks the Tenki calls in that example. In the agent examples it does not run a model turn.

Which example should I copy? For the SDK, run-code-in-a-sandbox. For a framework agent with a code-execution tool, langchain-code-interpreter. For a pluggable sandbox backend, vercel-ai-sdk.

Do the examples clean up their sandboxes? Sandboxes are billed per second. run.mjs disposes its sandbox with await using, and run.py uses 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. A new example ships a verify.mjs that CI runs against the live API, and adds a row to one of the tables above.

• Tenki documentation
• Sandbox SDK reference
• Tenki CLI reference
• Tenki MCP server
• Tenki nodes for n8n

MIT