Environments & Isolation

Isolation Layer: Virtual Terminal Sandbox & Execution Environment Security Boundaries

In-depth analysis of tools/environments/, local PTY redirection, and Docker volume mount security isolation
PTY and Docker Execution Isolation
📊 Fig 9-1: Standard I/O redirection, host directory mount & Docker container sandbox boundary diagram

💻 1. Execution Environment (Environments) Responsibility Design

When designing environments where the agent can run shell scripts and code, security is the overriding prerequisite. In the project tools/environments/, the system wraps execution environments with a unified interface:

  • tools/environments/local.py: Local execution environment. Implements pseudo-terminal redirection based on Unix PTY.
  • tools/environments/docker.py: Container-based isolated sandbox. Confines all commands executed by the LLM inside a read-only, highly-restricted Docker container.

🔒 2. Local PTY Pseudo-Terminal Redirection & Control (local.py)

If the agent directly called Python's subprocess.Popen to start a terminal, the LLM would be unable to interact (e.g., typing confirmations in the terminal or streaming top logs). To solve this, tools/environments/local.py implements low-level Unix PTY control:

  • pty.openpty() Interface: Creates a pseudo-terminal pair (Master and Slave devices) in the background, redirecting stdin, stdout, and stderr to the PTY slave device.
  • Streaming Listener & Hard Timeout: A background daemon thread monitors the Master output, pumps characters to the gateway and TUI frontend in real-time, while enforcing a hard timeout threshold. If no response is received within the limit, it sends a SIGKILL to force disconnection, completely eliminating zombie processes.
Terminal stream PTY bidirectional pipe
📊 Fig 9-2: Host sandbox controller and isolated environment (PTY master-slave devices) bidirectional redirection pipeline diagram

🛡️ 3. Docker Container Isolation & Security Boundary (docker.py)

For remote deployment or high-risk scenarios (such as auditing third-party downloaded scripts), local PTY can severely compromise host security. In tools/environments/docker.py, the system uses Docker containers to build a fully physically isolated sandbox defense:

  1. Read-Only Volume Mount: The system mounts only the current Workspace as a read-only disk into the container, preventing the LLM from tampering with system files (e.g., /etc, /lib).
  2. Namespace Isolation: When launching the container, it enforces independent PID, NET, IPC, and UTS namespaces. The LLM inside the container has no ability to probe the host's network or process topology.
  3. Security Filtering Mechanism: The container injects strict security_opts security attributes at startup, restricts Linux Capabilities (blocking most root system calls), and mounts Seccomp and AppArmor policies to ensure the sandbox is impenetrable.

🔗 Sub-Chapter Deep Dives

For a deeper understanding of virtual sandboxes and PTY interaction, we recommend the following technical sub-topics: