# Security Model for Running Untrusted Agent Code in Cua Sandboxes

> Discover the Cua security model for running untrusted agent code. Learn how Cua uses sandboxing with process isolation, privilege restriction, and network sandboxing for robust defense.

- Repository: [Cua/cua](https://github.com/trycua/cua)
- Tags: architecture
- Published: 2026-04-27

---

**Cua isolates untrusted agent code by executing it inside a lightweight virtual machine or container sandbox that provides defense-in-depth through strict process isolation, privilege restriction, network sandboxing, and a minimal SDK API surface.**

The trycua/cua project implements a comprehensive security model designed to safely execute arbitrary agent code without compromising the host system. By leveraging multiple isolation layers across Docker, QEMU, Lume, and Windows Sandbox runtimes, Cua ensures that malicious or buggy agents remain confined within ephemeral, unprivileged environments. This article examines the implementation details found in the Cua sandbox source code to explain exactly how the platform achieves secure execution.

## Architecture of the Cua Sandbox Security Model

The security model is implemented in [`libs/python/cua-sandbox/cua_sandbox/sandbox.py`](https://github.com/trycua/cua/blob/main/libs/python/cua-sandbox/cua_sandbox/sandbox.py) and relies on a defense-in-depth strategy that combines OS-level virtualization with strict API controls. The architecture prevents unauthorized access through six distinct isolation layers.

### Process and Filesystem Isolation

Each sandbox runs in its own OS instance—either a Docker container, QEMU VM, Lume VM, or Windows Sandbox—with a minimal filesystem that contains only the agent code, a small Python runtime, and the Cua SDK. The host filesystem is never mounted inside the guest.

In [`libs/python/cua-sandbox/cua_sandbox/runtime/docker.py`](https://github.com/trycua/cua/blob/main/libs/python/cua-sandbox/cua_sandbox/runtime/docker.py), containers are launched with `--read-only` root filesystems and user-namespace mapping to prevent write access to system directories. For QEMU-based sandboxes, [`libs/python/cua-sandbox/cua_sandbox/runtime/qemu.py`](https://github.com/trycua/cua/blob/main/libs/python/cua-sandbox/cua_sandbox/runtime/qemu.py) provisions a fresh disk image on each startup and explicitly avoids shared mounts, ensuring the guest operates within a completely isolated storage context.

### Privilege Restriction and Capability Limits

All sandbox processes execute as an unprivileged user (UID 1000) with no `sudo` rights and no Linux capabilities that could affect the host kernel. The Docker runtime applies default seccomp and AppArmor profiles to block dangerous system calls, while the QEMU and Lume runtimes disable hardware acceleration features that could allow host-side introspection. This least-privilege approach ensures that even if an agent compromises the guest OS, it cannot escalate privileges to attack the host.

### Network Sandboxing and RPC Controls

By default, sandboxes expose no inbound ports and block outbound traffic to arbitrary external services. All communication flows through a single, authenticated WebSocket or HTTP channel implemented in [`libs/python/cua-sandbox/cua_sandbox/transport/http.py`](https://github.com/trycua/cua/blob/main/libs/python/cua-sandbox/cua_sandbox/transport/http.py). This transport layer carries only validated Cua RPC messages, preventing agents from establishing unauthorized network connections or exfiltrating data to external endpoints.

### Limited SDK API Surface

Agents cannot directly access host resources such as the `os`, `subprocess`, or filesystem modules. Instead, they interact with the host exclusively through the Cua SDK, which exposes a restricted set of high-level abstractions including `screen`, `mouse`, `keyboard`, `clipboard`, and `terminal` operations defined in [`libs/python/cua-sandbox/cua_sandbox/interfaces/shell.py`](https://github.com/trycua/cua/blob/main/libs/python/cua-sandbox/cua_sandbox/interfaces/shell.py). All SDK calls are marshalled over the sandbox RPC boundary and executed within the isolated guest, ensuring the agent never holds direct references to host handles.

### Ephemeral Lifecycle and State Management

Sandboxes are designed to be short-lived disposable environments. After task completion, error conditions, or timeouts, the host invokes `destroy()` on the `Sandbox` class, which immediately stops the VM or container and deletes its disposable storage image. This ephemeral design prevents persistent threats by ensuring that any malicious state or modifications are destroyed along with the sandbox instance.

### OS-Level Isolation on Windows

For Windows hosts, Cua utilizes the built-in Windows Sandbox feature, which creates a Hyper-V-based virtual machine with kernel-level isolation and a temporary virtual hard disk (VHD). As documented in [`blog/windows-sandbox.md`](https://github.com/trycua/cua/blob/main/blog/windows-sandbox.md), this approach provides hardware-enforced isolation through Microsoft's native virtualization stack, offering stronger guarantees than software-based containerization alone.

## How the Security Model Works in Practice

The security workflow follows a strict lifecycle from creation to destruction, with each stage enforcing the isolation boundaries described above.

### 1. Sandbox Creation

When the host application calls `cua.sandbox.create(...)`, Cua selects the appropriate runtime based on the requested operating system and launches a fresh environment. The following example demonstrates initializing a sandbox with explicit runtime configuration:

```python
from cua_sandbox import Sandbox

# Create an ephemeral sandbox with specific resource limits

sandbox = await Sandbox.create(
    runtime="docker",  # or "qemu", "lume", "windows"

    image="cua-agent:latest",
    cpu_limit=2,
    memory_limit="4g"
)

```

At this stage, the runtime initializes an isolated filesystem, configures the unprivileged user context, and applies seccomp or hypervisor restrictions before the guest OS begins booting.

### 2. Agent Deployment

The untrusted agent code is securely copied into the sandbox's working directory and executed by the guest's Python interpreter. The environment contains only the Cua SDK and a carefully curated subset of the Python standard library, with dangerous modules removed or restricted.

### 3. RPC Communication Channel

Once the agent starts, it communicates with the host through the transport layer implemented in the `cua_sandbox/transport/` package. The following code illustrates how the host establishes the authenticated RPC connection:

```python

# Connect to the sandbox's RPC endpoint

await sandbox.connect()

# All subsequent interactions occur over the validated channel

result = await sandbox.rpc.call("screen.capture")

```

The transport validates all message boundaries and authentication tokens, rejecting any malformed or unauthorized requests before they reach the host.

### 4. Operation Execution

When the agent requests actions such as screen captures or input automation, these operations execute entirely within the sandbox guest. The agent loop in [`libs/python/cua/agent.py`](https://github.com/trycua/cua/blob/main/libs/python/cua/agent.py) spawns the sandbox and manages the connection without exposing host-side objects or handles to the guest process.

### 5. Secure Shutdown

After task completion, the host triggers destruction to eliminate the sandbox and all associated state:

```python

# Tear down the sandbox and delete all temporary storage

await sandbox.destroy()

```

This call immediately terminates the VM or container process and removes the ephemeral disk image, ensuring no forensic residue remains on the host system.

## Platform-Specific Security Hardening

Cua implements runtime-specific hardening measures to maximize isolation across different virtualization technologies:

- **Docker**: Uses `--read-only` root filesystems, user namespace remapping, and default seccomp/AppArmor profiles to restrict system calls and prevent privilege escalation.
- **QEMU/Lume**: Leverages hardware virtualization extensions with fresh disk images per execution and disabled shared folders to prevent host-guest data leakage.
- **Windows Sandbox**: Utilizes Hyper-V kernel-level isolation with automatic cleanup of temporary VHDs, providing enterprise-grade containment for Windows-based agents.

## Summary

- **Cua sandboxes** execute untrusted code inside isolated VMs or containers (Docker, QEMU, Lume, Windows Sandbox) with minimal filesystem access and no host mounts.
- **Privilege restriction** ensures all processes run as unprivileged users without capabilities, protected by seccomp, AppArmor, or hypervisor-level controls.
- **Network confinement** blocks arbitrary outbound traffic and routes all communication through a single authenticated RPC channel defined in the transport layer.
- **API limitation** forces agents to use the Cua SDK exclusively, preventing direct access to host filesystems, processes, or system calls.
- **Ephemeral design** ensures sandboxes are destroyed after use via the `destroy()` method, eliminating persistent threat vectors.
- **Platform hardening** provides runtime-specific protections including read-only filesystems, hardware virtualization isolation, and Windows Hyper-V containment.

## Frequently Asked Questions

### How does Cua prevent agents from accessing host files?

Cua prevents host file access by running agents in isolated virtual machines or containers that use fresh disk images without shared mounts. The Docker runtime mounts `--read-only` root filesystems and avoids bind-mounting host directories, while QEMU and Lume runtimes boot from pristine disk images that contain no host data.

### What happens if an agent attempts to execute privileged operations?

All sandbox processes run as unprivileged users (UID 1000) without `sudo` access or Linux capabilities. The Docker runtime applies seccomp and AppArmor profiles that block privileged system calls, and QEMU runtimes disable hardware features that could enable privilege escalation, causing unauthorized operations to fail at the kernel or hypervisor level.

### Can network traffic escape the Cua sandbox to external services?

No, by default sandboxes have no outbound internet access. All network traffic is restricted to a single authenticated RPC channel over WebSocket or HTTP, implemented in [`libs/python/cua-sandbox/cua_sandbox/transport/http.py`](https://github.com/trycua/cua/blob/main/libs/python/cua-sandbox/cua_sandbox/transport/http.py). This transport validates messages and prevents agents from establishing connections to arbitrary external endpoints.

### How does the Windows Sandbox implementation differ from Linux containers?

The Windows Sandbox implementation uses Microsoft's Hyper-V-based virtualization rather than containerization, creating a kernel-level isolated environment with a temporary virtual hard disk. Unlike Linux containers that rely on namespace isolation and seccomp, Windows Sandbox leverages hardware-assisted virtualization and automatic VHD cleanup to provide strong isolation guarantees for Windows-based agent execution.