Agent Sandbox
Isolated Kata Containers workspaces in which agents run commands, skill scripts, and app previews.
Component Category
AI tools / isolated code execution
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
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
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 for node, storage, network, sizing, and preview preparation, and Code sandbox for the tenant settings.
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-Cephor external S3-compatible storage, which holds saved workspaces.Gateway API, which publishes app preview hosts through the shared gateway.