AG2

AG2 is an open-source Python framework for building AI agents, formerly AutoGen. Its sandbox tools, SandboxShellTool and SandboxCodeTool, let an agent run shell commands and code in an environment you choose. BoxdEnvironment runs those tools on an isolated boxd machine. It is part of AG2 as the ag2.extensions.boxd extension (pull request), and it ships in AG2 1.3.1 and later.

Set up

Install AG2 and the boxd SDK

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

The anthropic extra is for the example below; use your model provider’s extra instead.

Create an API key

boxd auth keys create ag2 --org <your-org>
export BOXD_API_KEY=bxd_...

Machines are created and billed in the key’s organization.

Give the agent a machine

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:
    async with BoxdEnvironment() as 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())

asyncio.run(main())

Set ANTHROPIC_API_KEY for the model. The agent’s commands and code now run on the machine, in /home/boxd.

One machine per environment

The first tool call starts a machine, and every later call in the same environment reuses it, so files the agent writes stay there between calls. Leaving the async with block deletes the machine. Without async with, call await env.aclose(). SandboxCodeTool runs python and bash by default. The machine also has Node.js, so pass languages=("python", "bash", "javascript") to let the model run JavaScript too.

Configure the machine

from ag2.extensions.boxd import BoxdEnvironment, BoxdResources

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

Setting	What it does
`api_key`	The boxd API key. Defaults to `BOXD_API_KEY`.
`region`	The region to create the machine in, such as `fra`. Defaults to `BOXD_REGION`.
`name`	The machine’s name, unique in your organization. By default boxd picks one.
`image`	The guest image. Defaults to Ubuntu 24.04.
`env_vars`	Environment variables set on every command.
`labels`	Labels added to the machine. `created-by=ag2` is always set.
`resources`	One of boxd’s machine sizes: 1 vCPU and 4G, 2 and 8G, 4 and 16G, or 8 and 32G. Defaults to your organization’s size.
`isolated`	Create the machine isolated. Default `True`.
`timeout`	Seconds to wait for the machine to start, and for each command. Default 60.
`delete_after`	Seconds until boxd deletes the machine on its own. Default 3600; `None` turns it off.
`workdir`	The directory commands run in. Default `/home/boxd`, created if missing.

api_key, region, name, image, env_vars and labels also take an AG2 Variable, resolved for each conversation. One environment then serves several tenants, with one machine for each set of values.

What each machine gets

Isolation: the machine has no boxd credentials, no metadata endpoint, and no route to your organization’s other machines, so code the model writes can’t use your boxd account. Outbound internet stays on.
A deadline: a delete-after timer, one hour by default, deletes the machine even if your process dies before it closes the environment.
Commands as the boxd user, who has passwordless sudo. A command’s output is its stdout and stderr, and its exit code comes back unchanged.
A timeout: a command that runs past its timeout is stopped and returns exit code 124, without its partial output.
A label: every machine carries created-by=ag2, so boxd machine list --label created-by=ag2 shows any that a crashed run left behind.

AG2’s boxd guide covers the same setup, and the code execution page compares boxd with AG2’s other sandboxes.

Getting started

Guides

Integrations and automations

Use cases

References

Set up

One machine per environment

Configure the machine

What each machine gets