# Agent Sandbox (/docs/ai/components/agent-sandbox)



## Component Category [#component-category]

AI tools / isolated code execution

## Component Description [#component-description]

The agent sandbox gives an agent an isolated workspace in which it runs commands, installs packages, writes files, runs a skill's bundled scripts, and optionally serves a web app preview. BullSequana AI deploys the Kubernetes agent-sandbox controller v1.0.5 and runs each workspace as a pod in the `coreai-sandboxes` namespace, inside a Kata Containers 4.2.0 micro-VM with the `kata-qemu` RuntimeClass.

The sandbox is off by default. Once a site enables it, **Build** chats and ordinary chats that can create files use it. A platform administrator can turn it off for every tenant, and a tenant administrator for their own organization, with the **Code sandbox** switch.

## Why It Is Used [#why-it-is-used]

In BullSequana AI, the agent sandbox keeps code that agents and skills run away from the platform's own workloads and from other chats. Each workspace has its own virtual machine kernel, no Kubernetes credentials, and network access that the site controls.

## Learn More [#learn-more]

* [kubernetes-sigs/agent-sandbox on GitHub](https://github.com/kubernetes-sigs/agent-sandbox)
* [Kata Containers](https://katacontainers.io/)
* [Kata Containers on GitHub](https://github.com/kata-containers/kata-containers)

## Deployment notes [#deployment-notes]

Three components deliver the sandbox:

| Component       | Parent application | What it installs                                                                                                                                     |
| --------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kata-deploy`   | `common`           | The Kata Containers runtime on nodes labelled `workload=sandbox`, and the `kata-qemu` RuntimeClass                                                   |
| `agent-sandbox` | `coreai`           | The controller in `agent-sandbox-system`, its CRDs, the `coreai-sandboxes` namespace, its ResourceQuota and LimitRange, and an ingress NetworkPolicy |
| `llm-backend`   | `coreai`           | The sandbox template, a warm pool of two ready pods, the reaper that saves and stops idle sandboxes, and the optional preview proxy                  |

The BSQAI API claims one sandbox per chat from the warm pool. When a session is idle or reaches its maximum lifetime, the reaper saves the workspace to object storage and stops the pod; the next message restores it into a new pod. A customer organization's workspaces are saved in its own bucket, and the Global organization's in the `sandbox-workspaces` bucket.

The namespace quota allows 300 sandbox pods by default, warm pool pods included, shared by all tenants. Each pod requests 250m CPU and 512Mi memory and is limited to 1 CPU and 2Gi memory, plus the Kata VM overhead of 250m CPU and 160Mi memory.

`LLM_BACKEND_SANDBOX_EGRESS_MODE` sets the outbound traffic of every sandbox on the site: `internet`, the default, allows HTTPS to public addresses and cluster DNS; `blocked` allows none. App previews are off by default. With previews on, the preview proxy serves each chat's app on its own host under `sandbox.<base-domain>`, and admits only browsers that hold a preview session from the Portal.

See [Enable and operate agent code sandboxes](/docs/deployment/playbooks/agent-sandbox) for node, storage, network, sizing, and preview preparation, and [Code sandbox](/docs/administration/tenant-settings#code-sandbox) for the tenant settings.

## Interacts With [#interacts-with]

* `BSQAI API`, which claims, restores, and stops sandboxes, runs the agent's commands in them, and serves their files.
* `AI Web Portal`, which shows a sandbox's files and embeds its app preview in **Build** chats.
* `Kata Containers`, which runs each sandbox pod in its own lightweight virtual machine.
* `Rook-Ceph` or external S3-compatible storage, which holds saved workspaces.
* `Gateway API`, which publishes app preview hosts through the shared gateway.
