> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# AG2

> Run an AG2 agent's shell commands and code on an isolated boxd machine that lives as long as the environment.

![The AG2 logo inside the boxd card.](https://mintcdn.com/azin/7IWa9uzq2xw7Urj2/images/boxd-x-ag2.png?fit=max\&auto=format\&n=7IWa9uzq2xw7Urj2\&q=85\&s=7385fb5037c7da5e29359f2459b75545)

[AG2](https://ag2.ai) 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](https://github.com/ag2ai/ag2/pull/3606)), and it ships in AG2 1.3.1 and later.

## Set up

**1. Install AG2 and the boxd SDK**

```bash theme={"theme":"github-dark"}
pip install 'ag2[anthropic]' 'boxd>=0.3.0,<1'
```

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

**2. Create an API key**

```bash theme={"theme":"github-dark"}
boxd auth keys create ag2 --org <your-org>
export BOXD_API_KEY=bxd_...
```

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

**3. Give the agent a machine**

```python theme={"theme":"github-dark"}
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

```python theme={"theme":"github-dark"}
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](https://docs.boxd.sh/guides/machine-specs.md): 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](https://docs.boxd.sh/guides/delete-after.md) 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](https://github.com/ag2ai/ag2/blob/main/website/docs/user-guide/extensions/boxd.mdx) covers the same setup, and the [code execution page](https://github.com/ag2ai/ag2/blob/main/website/docs/user-guide/tools/code_execution.mdx) compares boxd with AG2's other sandboxes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.