Skip to content

Tenki Sandbox

The ag2.extensions.tenki module runs AG2 shell and code tools in isolated Tenki Sandbox sessions. It implements AG2's native sandbox factory, so one environment provides persistent files across tool calls and deterministic cleanup.

Installation#

Install AG2, your model provider, and Tenki's Python SDK:

pip install "ag2[anthropic]" "tenki>=0.5.4,<1"

Create an API key in Tenki and export it:

export TENKI_API_KEY="tk_your_api_key"

The SDK uses https://api.tenki.cloud by default. Set TENKI_API_URL only when targeting another Tenki deployment.

Use Tenki with an agent#

Use the environment as an async context manager. The sandbox is reused for every shell or code call inside the scope and terminated when the scope exits.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import asyncio

from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.extensions.tenki import TenkiEnvironment
from ag2.tools import SandboxCodeTool, SandboxShellTool

async def main() -> None:
    env = TenkiEnvironment()
    async with env:
        agent = Agent(
            "developer",
            config=AnthropicConfig(model="claude-sonnet-4-6"),
            tools=[SandboxShellTool(env), SandboxCodeTool(env.code_environment())],
        )
        reply = await agent.ask("Write hello.txt, then read it with Python.")
        print(await reply.content())

if __name__ == "__main__":
    asyncio.run(main())

TenkiEnvironment() discovers the sole workspace visible to the API key. If the key can access multiple workspaces, select one explicitly:

1
2
3
from ag2.extensions.tenki import TenkiEnvironment

env = TenkiEnvironment(workspace_id="your-workspace-id")

Configure the sandbox#

The default working directory is /home/tenki. Inbound networking is disabled, outbound networking is enabled, and every sandbox has a 15-minute max_duration backstop if client cleanup cannot run.

Use code_environment() for SandboxCodeTool

A Tenki sandbox runs as uid=1000(tenki) with a read-only root, so it works out of /home/tenki and its image ships python3 rather than python.

TenkiEnvironment satisfies WorkdirAware, so SandboxShellTool(env) reports the real working directory to the model on its own — no extra wiring.

SandboxCodeTool needs one: pass env.code_environment() instead of env to get a CodeAdapter whose python runner is python3. It accepts languages= to restrict what the tool runs.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from ag2.extensions.tenki import TenkiEnvironment, TenkiResources

env = TenkiEnvironment(
    workspace_id="your-workspace-id",
    name="my-agent-sandbox",
    image="workspace/image:tag",
    env_vars={"APP_ENV": "sandbox"},
    resources=TenkiResources(cpu_cores=2, memory_mb=4096, disk_size_gb=5),
    timeout=60,
    max_duration=900,
)
Parameter Default Purpose
api_key TENKI_API_KEY API authentication
api_url TENKI_API_URL or production API endpoint
workspace_id Auto-detected when unique Tenki workspace scope
name ag2 Session name for identification
image Tenki default image Registry image reference
env_vars {} Environment variables applied to the sandbox
resources Tenki defaults CPU, memory, and disk overrides
timeout 60 seconds Sandbox startup and command timeout
max_duration 900 seconds Server-enforced session lifetime backstop
workdir /home/tenki Working directory for commands and files

All credential and sandbox selection parameters accept Variable values for per-request resolution. Always close the environment with async with or await env.aclose(); max_duration is a fail-safe, not the normal cleanup path.

Testing#

The bundled unit tests mock the Tenki SDK and run offline, so no Tenki account is needed for the AG2 test suite. Exercising the integration against real sandboxes requires a Tenki account and a TENKI_API_KEY.

Maintainer: @camcalaquian / Tenki.