boxd

The ag2.extensions.boxd module runs AG2 shell and code tools on boxd machines. A boxd machine is a full Linux microVM (KVM) with a persistent disk that starts in about a second. The extension implements AG2's native sandbox factory, so one environment keeps its files across tool calls and deletes its machine when you close it.

Installation#

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

pip install "ag2[anthropic]" "boxd>=0.3.0,<1"

Create an API key in the boxd console and export it:

export BOXD_API_KEY="your-boxd-api-key"

Set BOXD_REGION (for example fra) to create machines in a specific region.

Use boxd with an agent#

Use the environment as an async context manager. The machine is reused for every shell or code call inside the scope and deleted 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.boxd import BoxdEnvironment
from ag2.tools import SandboxCodeTool, SandboxShellTool

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

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

Configure the machine#

The default image is Ubuntu 24.04. Commands run as the user boxd (with passwordless sudo) in /home/boxd, and the image ships python, bash, node, git and Docker. BoxdEnvironment satisfies WorkdirAware, so SandboxShellTool(env) reports the real working directory to the model on its own, and SandboxCodeTool(env) works without a custom CodeAdapter. SandboxCodeTool enables python and bash by default; pass languages=("python", "bash", "javascript") to let the model run Node too.

Machines are created isolated by default: they have no in-machine boxd credential, no metadata endpoint and no private network peers, so code the model writes cannot reach your boxd account. Outbound internet access stays on. Every machine also gets a one-hour delete_after timer, which boxd enforces even if your process dies before it can clean up.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

from ag2.extensions.boxd import BoxdEnvironment, BoxdResources

env = BoxdEnvironment(
    region="fra",
    name="my-agent-sandbox",
    env_vars={"APP_ENV": "sandbox"},
    labels={"team": "data"},
    resources=BoxdResources(vcpu=4, memory="16G"),
    timeout=60,
    delete_after=900,
)

api_key, base_url, region, name, image, env_vars and labels accept Variable values for per-request resolution. Always close the environment with async with or await env.aclose(); a machine whose delete failed is retried by the next aclose(), and delete_after is a fail-safe, not the normal cleanup path.

A command that runs past its timeout is killed on the machine and returns exit code 124. Its partial output is not returned.

Testing#

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

Maintainer: boxd.