VSI GLOBAL // ENTERPRISE ARCHITECTURE

Agent Sandboxing Environment

4 min read

Agent Sandboxing Environment

Deliverable AGT-007. Structure per cc02-standards/SYSTEM-STANDARD.md. Every component traces to a design basis (NEED/REQ) and to an acceptance criterion.

1. Purpose and Design Basis

1.1 Scope and Objective

The Agent Sandboxing Environment provides isolated runtime environments (virtual containers) for all local agent execution sessions, preventing access to the host file system and restricting network communication.

1.2 Design Basis

This system secures the host OS from untrusted LLM tool executions. It maps the containerized workflow pattern (claude -p with allowlisted tool set) onto kernel-isolated namespaces and AppArmor profiles, guaranteeing that agent code cannot run arbitrary shell commands on the host or access credentials not explicitly passed to the sandbox environment.

1.3 Needs

  • NEED-AGT-007-01: Developer/PI (CS) needs to isolate agent execution environments to prevent unauthorized filesystem access.
    • Source: CS (Developer / Systems Engineer) security architecture plan.
    • Context: Running local LLM agents requires strict containment to avoid unauthorized execution of shell tools or file deletion on the host.
  • NEED-AGT-007-02: The Systems Engineer (CS) requires that LLM secrets and credentials are never written to disk inside the agent execution workspace.
    • Source: CS (Systems Engineer) security architecture plan.
    • Context: If an agent writes API keys to a log or temporary workspace file, they could be leaked or exfiltrated.

1.4 Requirements

  • REQ-AGT-007-01 (Traceability: NEED-AGT-007-01): During all active agent run sessions, the Agent Sandboxing Environment shall restrict agent tool execution to a throwaway virtual container [VR-AGT-007-01].
    • Verification Method: Test (T)
  • REQ-AGT-007-02 (Traceability: NEED-AGT-007-01): Under the condition that a tool call is executed, the Agent Sandboxing Environment shall log the API endpoint, parameters, and response status [VR-AGT-007-02].
    • Verification Method: Inspection (I)
  • REQ-AGT-007-03 (Traceability: NEED-AGT-007-02): The sandbox shall restrict container write permissions to a memory-backed temporary directory (tmpfs) that is destroyed upon container exit [VR-AGT-007-03].
    • Verification Method: Demonstration (D)

2. Architecture As Built

The Agent Sandboxing Environment is a kernel-enforced container execution system (using Docker Engine and custom Linux kernel namespace configs). It intercepts agent launch commands, mounts only the designated project directory as a read-only volume, and provides a volatile memory mount (tmpfs) for temporary operations. Outbound network traffic is routed through explicit network rules that allow connection to approved services only.

Data flow:

  1. The agent manager invokes the containerized execution wrapper for an agent session.
  2. The runtime applies the AppArmor policy profile and mounts the working directory as read-only.
  3. The Docker engine provisions a new container instance from the local base image, mounting /tmp as a writeable tmpfs volume.
  4. Tool executions inside the container are logged via the docker logging socket.
  5. The log dispatcher captures stdout and API calls, writing them to syslog.
  6. Upon process completion, the container exits and all tmpfs data is discarded.
+-------------------------------------------------------------------------+
| AGT-007 Agent Sandboxing Environment                                    |
|                                                                         |
|  [Host Docker Daemon]                                                   |
|         |                                                               |
|         v                                                               |
|  [User Namespaces + AppArmor Policies]                                  |
|         |                                                               |
|         v                                                               |
|  [Sandbox Container (CPU/Memory limits)] ---> [Memory tmpfs (write)]    |
+-------------------------------------------------------------------------+

3. Components and Bill of Materials

ComponentSpecVendor / LinkPriceTierStatusTraceability
Container HostLightweight virtual container host daemon (Docker Engine v25+)Docker$0.00-SELECTEDREQ-AGT-007-01
Sandbox ConfigurationAppArmor profile policies and Seccomp filtersOS$0.00-SELECTEDREQ-AGT-007-01
Logging DaemonDocker daemon logging interface with syslog hookOS$0.00-SELECTEDREQ-AGT-007-02

4. Build and Deployment

4.1 Host Provisioning

  1. Install Docker Engine and configure the system user group mapping: apt-get install docker-ce.
  2. Build the default agent execution base image agent-base:latest utilizing a python-slim base: docker build -t agent-base:latest -f docker/Dockerfile.agent ..

4.2 Security Setup

  1. Deploy the custom AppArmor profile policy file /etc/apparmor.d/docker-agent-sandbox and load it: apparmor_parser -r -W /etc/apparmor.d/docker-agent-sandbox.
  2. Configure the docker daemon configuration /etc/docker/daemon.json to enable user namespace remapping.
  3. Place the agent execution wrapper script inside /usr/local/bin/agent-sandbox.

5. Hardening Baseline

  • Process Hardening: Run containers with the --security-opt="no-new-privileges:true" runtime flag to prevent privilege escalation.
  • Resource Constraints: Enforce strict CGroups limits, constraining memory consumption to [N] MB and CPU allocation to [N] shares.
  • Root Directory Lock: Enforce a read-only root filesystem (--read-only), utilizing a memory-backed temporary mount (--tmpfs /tmp:rw,noexec,nosuid,size=[N]m) for local workspace operations [REQ-AGT-007-03].

6. Integration Points

InterfaceTypeDirectionContract
Container ExecutionCommand / APIConsumedLocal agent execution wrapper commands passed to Docker
Audit LogsStream (syslog)ProducedOutbound syslog audit trails written to the syslog daemon

7. Acceptance Tests

CriterionMethodExpected ResultReference
REQ-AGT-007-01TestRun an agent command attempting to write to /usr/local/bin and verify access denial.VR-AGT-007-01
REQ-AGT-007-02InspectionAudit the container syslog stream and confirm all executed commands, arguments, and API returns are fully logged.VR-AGT-007-02
REQ-AGT-007-03DemonstrationRun an agent write command to /tmp, exit the container, and verify the file is completely absent upon next launch.VR-AGT-007-03

8. Run and Maintenance Handover

  • Launch Syntax: docker run --rm --read-only --tmpfs /tmp --security-opt apparmor=docker-agent-sandbox agent-base, or via the host wrapper: agent-sandbox --image agent-base --dir <workspace_path> --command <cmd>.
  • Audit Log Path: Execution outputs and stderr are logged to /var/log/agent-sandbox/audit.log.
  • Update Cadence: Re-build the base agent images monthly to incorporate upstream security patches.
  • Ownership: Systems Engineer (CS).

END OF SYSTEM

Model wiring

Generated from cell frontmatter at publish time.

Graph View

Backlinks