AI AGENT SANDBOXING VOCABULARY · ISOLATE → EXECUTE → INSPECT → EXPORT → DISCARD
Picture a student practising a chemical experiment. A supervised laboratory bench has boundaries: the right materials, a clear procedure, an appropriate place for waste, and rules about what must never be taken outside. AI agents that run code or work with files need a similar idea. AI agent sandboxing vocabulary explains how software is given a deliberately bounded workspace for operations that could otherwise affect a host machine, private documents, network services or production systems.
The aim of sandboxing is limited capability with controlled consequences. Terms such as execution environment, container, virtual machine, filesystem isolation, read-only mount, network egress, least privilege, resource quota, snapshot, artifact promotion and sandbox escape tell a precise story: what can an agent touch, where can it run, what may leave, and what happens afterward?
This guide belongs to the eduKateSG Vocabulary Hub and the Core Aim of Vocabulary Mastery series. It connects to AI Agent Identity Vocabulary for permissions and AI Guardrail Design Vocabulary for checks. Its unique focus is the execution environment itself: isolation of files, processes, network and resources. Not every workspace labelled ‘sandbox’ provides strong security isolation.
Central proposition: A sandbox is useful only when its boundaries are real, measurable and appropriate to the threat. A separate working folder or a friendly instruction to be careful is not automatically a security boundary.
A practical reason to learn this vocabulary
An educational assistant might receive a student’s spreadsheet and be asked to calculate how marks change when individual topics improve. If the agent uses a programming tool to inspect the spreadsheet, code should run under permissions suited to that file and task. It should not suddenly gain access to staff payroll documents, production WordPress credentials or unrestricted outbound network connections.
A sandbox can protect the rest of the system if the file is malformed, a parser is vulnerable or a generated command behaves unexpectedly. But the word ‘sandbox’ alone does not guarantee this. A local directory with no operating-system confinement is an organisational workspace, not a strong isolation barrier against arbitrary commands.
The language map: sandbox terms worth knowing
| Term | Plain-English meaning | Question it answers |
|---|---|---|
| Sandbox | A deliberately bounded environment for executing operations. | Where is the agent allowed to work? |
| Host | The underlying machine or platform providing compute. | What system lies outside the sandbox? |
| Execution environment | The runtime where code, commands or tools execute. | Where does this action really run? |
| Container | An isolated operating-system environment sharing a host kernel under particular controls. | What boundaries separate processes? |
| Virtual machine | A virtual computer with its own guest operating system. | What isolation model is being used? |
| Namespace | A mechanism that can separate process views of resources. | What does this process get to see? |
| Filesystem mount | A connection that exposes a host or external storage path to an environment. | Which files are visible? |
| Read-only mount | Storage exposed without ordinary write access. | Can the agent modify the source? |
| Working directory | The default folder for a command or program. | Where do relative paths point? |
| Workspace manifest | A declaration of which files and capabilities a new workspace should start with. | What is intentionally included? |
| Least privilege | Providing only the permissions necessary for the task. | What access could be removed? |
| Run-as identity | The user identity under which processes or filesystem tools operate. | Whose operating-system rights are used? |
| Network egress | Outbound network communication from the environment. | Where may the agent send data? |
| Ingress | Inbound connectivity permitted to the environment. | What can connect to the process? |
| Resource quota | A limit on memory, CPU, storage or execution time. | How much can it consume? |
| Time limit | A bound on how long work may continue. | When should it stop? |
| Snapshot | A stored representation of selected workspace contents or state. | Can this state be restored? |
| Ephemeral environment | An environment intended for temporary use and disposal. | What remains after the session? |
| Artifact | An output file or result produced inside the workspace. | What can be safely exported? |
| Artifact promotion | Moving a reviewed output into a more trusted destination. | What crosses the boundary? |
| Sandbox escape | A failure where activity gains access beyond the intended isolation boundary. | Can code reach the host? |
| Secret | A credential such as an API token or password. | Is confidential authority exposed? |
| Cleanup | Disposal or reset of resources after work ends. | What data or processes remain? |
Sandbox versus folder versus container versus virtual machine
A folder offers convenience and organisation; by itself it may not stop a process from reading other accessible host files. A container can provide process and filesystem isolation, but its actual security depends on runtime configuration, mounts, user privileges and other host controls. A virtual machine offers a different isolation architecture, with a separate guest operating system. Hosted sandboxes depend on the provider’s documented boundaries and operational configuration.
| Environment | What it can provide | What not to assume |
|---|---|---|
| Dedicated folder | Predictable file placement and cleanup. | That commands cannot read outside the folder. |
| Local process runner | Simple execution on a developer’s machine. | Operating-system-level sandboxing. |
| Container-backed sandbox | A bounded process and filesystem environment when configured appropriately. | That host mounts, privileged mode or network access are harmless. |
| Virtual-machine sandbox | A guest environment separated by a virtualization layer. | That every VM is automatically patched or safely configured. |
| Hosted isolated runtime | Provider-managed compute and lifecycle features. | That isolation, egress and retention policies are the same everywhere. |
The OpenAI Agents SDK sandbox-client documentation makes a particularly important distinction: its Unix-local sandbox client runs host processes and does not add operating-system confinement, whereas its Docker client is designed for container-backed execution. This is a powerful reminder to treat product names as descriptions of an interface, not proof of the security strength of the backend.
Three boundaries to draw on a whiteboard
1. Filesystem boundary
Which directories and files can the agent see? A useful setup can stage selected learning resources into the workspace, expose source material read-only where practical and restrict writable areas to designated output folders. Mounting a broad host directory defeats many benefits of isolation because the agent may then access files unrelated to the task.
2. Process and resource boundary
Which programs can run, as which user, for how long and with which resource limits? Generated code can accidentally use excessive memory or create runaway loops. An appropriate timeout, CPU or memory budget and process cleanup help reduce disruption. The precise controls depend on the sandbox backend and available infrastructure.
3. Network boundary
Can the workspace reach the public internet, local network or private APIs? This matters when source material is untrusted. A malicious instruction inside a document might try to make the agent send private content elsewhere. Restricting outbound connections to necessary destinations and keeping secrets out of the execution environment reduces opportunities for exfiltration.
A worked example: checking a Primary 6 Science worksheet
Suppose an eduKateAI assistant is asked to review a worksheet containing questions on evaporation, condensation and heat. It needs to extract text from a supplied document, identify the key concepts and prepare a short revision packet. The sheet itself is data from an external source, and a document parser may have software weaknesses or unexpected behaviour.
The application can prepare a sandbox with only the worksheet and relevant approved reference material. The agent runs the parser inside that bounded environment. A result validator checks whether the extracted questions are complete and readable. The educator-facing answer is then built from reviewed text. If the parser crashes or the worksheet is corrupted, the system reports the limitation rather than silently fabricating missing questions.
| Phase | Bounded operation | Evidence of safe completion |
|---|---|---|
| Prepare | Stage worksheet and allowed references only. | Manifest or file list confirms the intended inputs. |
| Execute | Run the parser with restricted privileges and resources. | Process ends with inspectable status. |
| Inspect | Check extracted content and identify malformed sections. | Uncertain material marked for review. |
| Create | Generate a draft revision packet in the workspace. | Output file exists in the designated area. |
| Review | Validate level, accuracy, data handling and file contents. | Approved artifact and documented checks. |
| Export | Move the approved packet to its intended destination. | External result or saved artifact verified. |
| Dispose | Stop processes and apply workspace retention policy. | Temporary resources handled as intended. |
The one-way-door problem: a safe output is not the same as a safe execution
Even when code runs in a sandbox, its output may be used outside it. Imagine the agent generates HTML for a public teaching page. A harmless-looking string could become executable markup if the publishing system inserts it without safe handling. Another output could contain incorrect educational claims. Execution isolation helps manage what code can do while it runs; it does not establish factual accuracy or safe output interpretation.
This is why artifact promotion matters. Before outputs leave a lower-trust workspace, the receiving application can inspect types, contents, destination and permissions. In an editorial workflow, generated drafts should undergo factual and format checks before a separate authorised WordPress publication operation.
Workspace manifest: choosing what enters before an agent starts
A manifest describes a planned starting workspace. It might include a repository, a set of documents, a scratch directory, and approved mounts. The OpenAI Agents SDK sandbox architecture uses a manifest for the initial workspace and separate capabilities for features such as shell, filesystem and memory. A manifest is not automatically a record of every file that later appears in a reused workspace.
This distinction is important for reproducibility. A fresh workspace can begin from a known set of files, while a reused session may include edits and outputs from earlier runs. Teams should identify whether a given answer was produced from a clean input snapshot or from a workspace containing prior changes.
Persistent sandboxes: convenience and risk travel together
A persistent workspace lets an agent pick up its work after a pause. That can save effort on long writing or research tasks. But it also retains files, intermediate outputs and potentially sensitive material. A snapshot can help resume, yet it may carry an old credential, stale syllabus text or data that should no longer be accessible. Reusing a workspace requires the same attention to retention, authorisation and cleanup as creating it.
A student worksheet should not become a permanent input to unrelated tasks merely because it remains in a convenient shared folder. Similarly, a research artifact created for one education centre should not automatically be available to another centre. Identity and isolation boundaries must match the actual intended users.
Why ‘read-only’ and ‘network disabled’ are not universal promises
A declared read-only mount must be enforced by the chosen backend. A manifest entry or configuration string does not help if the runtime ignores it. A system can also have multiple network paths: public outbound traffic, local service access and mounted network storage. Developers should test the actual controls rather than infer security from their names.
Even strong isolation is not a guarantee against every vulnerability. Host configuration, software updates, kernel exposure, privilege settings and provider security all matter. The appropriate objective is to reduce the attack surface and contain plausible failures with multiple independently enforced controls.
A simple threat-model exercise
Take a hypothetical tutoring assistant that can execute code to make mathematics charts. Identify the assets worth protecting: student documents, teacher feedback, website publishing credentials and the host server. Now imagine three problems: an accidental infinite loop, a corrupted spreadsheet that triggers unexpected parser behaviour and untrusted file content instructing the agent to upload a report to an unrelated service.
The first problem calls for resource limits and timeouts. The second calls for suitably isolated execution and validated inputs. The third calls for strict network access, separation of source text from instructions and independent permissions on outbound actions. One instruction such as ‘work carefully’ does not solve all three.
Security controls and their true limits
| Control | Main purpose | Blind spot |
|---|---|---|
| Restricted file mounts | Limit accessible source and output files. | Incorrect mounts may expose too much. |
| Non-privileged user | Reduce what a process may do. | Other privileges or exposed services may still matter. |
| Container or VM boundary | Contain processes within an execution environment. | Isolation can fail through misconfiguration or vulnerabilities. |
| Network egress policy | Limit external communication. | Does not by itself establish content accuracy. |
| CPU, memory and time quotas | Limit runaway resource consumption. | Does not prevent every logical error. |
| Read-only references | Preserve original input artifacts. | Agent could still create misleading derivatives. |
| Output validation | Inspect produced files and claims. | Cannot retroactively undo a harmful external action. |
| Credential separation | Keep powerful access outside lower-trust processes. | Credentials must still be safely managed by external services. |
| Cleanup and retention | Reduce unnecessary persistence. | Backups and snapshots may require their own policies. |
Student-friendly practice: explain three words
Sandbox: ‘a workspace that is deliberately bounded by technical controls.’ Mount: ‘a connection exposing storage inside that workspace.’ Egress: ‘outbound network access’. Now apply them: if a maths-plotting agent needs two data files and no external website, which storage and network access should it receive? As little as necessary for the task, with the restrictions enforced by the backend.
For a deeper challenge, explain why a Docker container running with excessive privileges and a broad writable host mount may defeat its intended security purpose. Then compare it with a non-privileged process that has only selected read-only inputs and a dedicated output folder.
Common sandboxing misunderstandings
- ‘It has a sandbox folder, so it is isolated’: a folder alone may not confine host processes.
- ‘A container is always secure’: examine privileges, mounts, network and runtime settings.
- ‘The agent cannot see the internet, so nothing can escape’: also inspect mounted paths, outputs and connected services.
- ‘The generated file is safe because code ran inside a sandbox’: inspect artifacts before promotion.
- ‘A reused session is always clean’: persistent state may contain old or sensitive material.
- ‘A snapshot is an anonymised backup’: it may preserve sensitive files and metadata.
- ‘All hosted sandboxes work alike’: compare provider documentation and test boundaries.
- ‘A model promise enforces permissions’: rely on runtime and service controls instead.
Frequently asked questions
What is AI agent sandboxing?
It is the practice of executing an agent’s commands or tools inside an appropriately bounded environment so their access to files, processes, networks and resources can be controlled.
Is a sandbox the same as a container?
No. A container is one possible technology for sandbox execution. Other implementations may use virtual machines, hosted runtimes or local processes with different security properties.
Does a local working directory isolate agent code?
Not by itself. A process may still be able to access other resources permitted by the host operating system and user account.
Why is network egress important?
It controls outbound connections, reducing opportunities for unnecessary external access or data transmission.
Can a sandbox be persistent?
Yes. Some environments support session reuse and snapshots, but persistent data and credentials then need deliberate lifecycle and privacy controls.
Is sandboxing enough to stop prompt injection?
No. Sandboxing can limit possible effects, but applications still need instruction boundaries, tool permissions, source checks and output validation.
Should learners run unfamiliar code directly on their main machine?
Untrusted code should be handled using an appropriately isolated environment and suitable supervision rather than assuming a normal folder is safe.
References and connected learning
- OpenAI Agents SDK — Sandbox Agents quickstart (workspaces, capabilities and execution choices).
- OpenAI Agents SDK — Sandbox clients (local, Docker and hosted backends).
- OpenAI Agents SDK — Sandbox concepts (manifests, sessions and snapshots).
- AI Prompt Injection Vocabulary (instructions hidden in untrusted content).
- AI Tool Output Validation Vocabulary (checking results before use).
- AI Guardrail Design Vocabulary (where to enforce controls).
- AI Workflow Recovery Vocabulary (persistent state and safe resumption).
- Immutable eduKateSG learning reference (structured explanations for learners).
The AI agent sandboxing vocabulary standard
Mastery means that a learner can name the host and execution environment, identify which files, processes and destinations are accessible, distinguish a local folder from actual isolation, explain how output crosses the boundary and propose suitable cleanup. The best sandbox is not one that simply claims to be safe. Its permissions, resource limits and lifecycle can be inspected and tested against the work it is supposed to perform.