# Configuring CodeExecutorAgent for Secure Code Execution in AutoGen

> Securely run AI code with AutoGen's CodeExecutorAgent. Learn how to use Docker and custom approval functions for safe code execution and agent security.

- Repository: [Microsoft/autogen](https://github.com/microsoft/autogen)
- Tags: how-to-guide
- Published: 2026-03-07

---

**To configure secure code execution in AutoGen, use the `CodeExecutorAgent` with a Docker-based executor and a custom `approval_func` to vet every code snippet before execution.**

The `CodeExecutorAgent` in the microsoft/autogen repository enables large language models to generate and run code within isolated environments. Configuring this agent for secure code execution requires understanding its dual-layer architecture and implementing proper sandboxing and approval mechanisms.

## Architecture of the CodeExecutorAgent

The agent operates through two distinct layers that separate orchestration from execution.

### Agent Layer

Located in [`autogen_agentchat/agents/_code_executor_agent.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/agents/_code_executor_agent.py), the agent layer handles conversation orchestration, extracts markdown code blocks, and manages the execution-reflection loop. It processes incoming `TextMessage` objects and coordinates with the underlying code executor.

### Code Executor Layer

The execution layer provides the actual sandbox environment. AutoGen offers two implementations:

- **Docker executor**: [`autogen_ext/code_executors/docker/_docker_code_executor.py`](https://github.com/microsoft/autogen/blob/main/autogen_ext/code_executors/docker/_docker_code_executor.py) provides OS-level isolation through containers.
- **Local executor**: `autogen_ext.code_executors.local.LocalCommandLineCodeExecutor` runs code in local subprocesses and is suitable only for debugging trusted code.

## Secure Execution Workflow

The `CodeExecutorAgent` follows a six-step pipeline to ensure safe code execution.

### 1. Message Intake and Code Extraction

The agent receives a `TextMessage` containing markdown code blocks. The `_extract_markdown_code_blocks` method parses content using a regex built from `self._supported_languages_regex` to identify executable snippets.

### 2. Approval Gate

Before execution, the agent checks for an `approval_func` callback. This function receives an `ApprovalRequest` containing the extracted code and returns an `ApprovalResponse` with an `approved` boolean and reason string. Without this function, the agent raises a runtime warning to remind developers to implement security vetting.

### 3. Sandboxed Execution

Approved code passes to the `CodeExecutor`. The `DockerCommandLineCodeExecutor` writes each block to a file in a working directory and executes it inside a Docker container with `auto_remove=True`. The executor enforces timeouts, isolates filesystems via volume mounts, and supports GPU device requests.

### 4. Result Normalization

The executor returns a `CodeResult` object. The agent normalizes empty outputs and non-zero exit codes into explanatory messages.

### 5. Event Emission

The agent yields a `CodeExecutionEvent` and adds the result to the model context for conversation continuity.

### 6. Reflection Loop

If a `model_client` is configured, the agent feeds execution outcomes back to the LLM to generate reflective responses, completing the iteration cycle.

## Security-Focused Configuration Options

Configure these parameters in `CodeExecutorAgent` and `DockerCommandLineCodeExecutor` to harden your deployment:

- **`approval_func`**: Implement `SyncApprovalFunc` or `AsyncApprovalFunc` to programmatically or manually vet code before execution.
- **Docker executor**: Use `DockerCommandLineCodeExecutor` instead of local execution to ensure OS-level isolation with `auto_remove=True` and filesystem isolation.
- **`work_dir` and `bind_dir`**: Restrict which host paths are visible inside the container. Defaults to `tempfile.TemporaryDirectory` for isolation.
- **`extra_volumes` and `extra_hosts`**: Explicitly whitelist additional mounts or hostname mappings rather than exposing the entire filesystem.
- **`timeout`**: Limit execution time to prevent runaway processes (default 60 seconds).
- **`delete_tmp_files`**: Remove temporary source files after execution when set to `True`.
- **`stop_container`**: Guarantee container cleanup when the executor closes or the process exits.

## Implementing a Secure CodeExecutorAgent

This complete example demonstrates a secure configuration using Docker isolation and a custom approval function:

```python
import asyncio
from autogen_agentchat.agents import CodeExecutorAgent, ApprovalRequest, ApprovalResponse
from autogen_agentchat.messages import TextMessage
from autogen_ext.code_executors.docker import DockerCommandLineCodeExecutor
from autogen_core import CancellationToken

def safe_approval(request: ApprovalRequest) -> ApprovalResponse:
    """Simple whitelist: only allow pure Python print statements."""
    if "print(" in request.code and "import " not in request.code:
        return ApprovalResponse(approved=True, reason="Allowed safe print")
    return ApprovalResponse(approved=False, reason="Disallowed operation")

async def main() -> None:
    # Initialize Docker-based executor for isolated sandboxing

    executor = DockerCommandLineCodeExecutor(work_dir="coding")
    await executor.start()

    # Create agent with security approval gate

    agent = CodeExecutorAgent(
        name="secure_executor",
        code_executor=executor,
        approval_func=safe_approval,  # Security gate

    )

    # Task containing a code block

    task = TextMessage(
        content='''
Here is a snippet to run:

```python
print("Hello, secure world!")

```

''',
        source="user",
    )

    # Execute with cancellation support

    response = await agent.on_messages([task], CancellationToken())
    print("Agent reply:", response.chat_message.content)

    # Cleanup

    await executor.stop()

asyncio.run(main())

```

This pattern aligns with the test suite in [`tests/test_code_executor_agent.py`](https://github.com/microsoft/autogen/blob/main/tests/test_code_executor_agent.py) and the implementation in [`_code_executor_agent.py`](https://github.com/microsoft/autogen/blob/main/_code_executor_agent.py).

## Key Source Files

Understanding these files helps you customize and audit the secure execution pipeline:

- **[`autogen_agentchat/agents/_code_executor_agent.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/agents/_code_executor_agent.py)**: Core agent implementation, approval handling, and execution loop. [View on GitHub](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_code_executor_agent.py)

- **[`autogen_ext/code_executors/docker/_docker_code_executor.py`](https://github.com/microsoft/autogen/blob/main/autogen_ext/code_executors/docker/_docker_code_executor.py)**: Docker-based sandbox configuration, volume mounting, and container lifecycle management. [View on GitHub](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-ext/src/autogen_ext/code_executors/docker/_docker_code_executor.py)

- **[`autogen_ext/code_executors/local/_local_code_executor.py`](https://github.com/microsoft/autogen/blob/main/autogen_ext/code_executors/local/_local_code_executor.py)**: Local subprocess executor for trusted debugging environments. [View on GitHub](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-ext/src/autogen_ext/code_executors/local/_local_code_executor.py)

- **[`tests/test_code_executor_agent.py`](https://github.com/microsoft/autogen/blob/main/tests/test_code_executor_agent.py)**: Test suite demonstrating approval functions and Docker integration patterns. [View on GitHub](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/tests/test_code_executor_agent.py)

## Summary

- The `CodeExecutorAgent` in microsoft/autogen separates orchestration from execution to enable safe LLM-generated code running.
- **Docker isolation** via `DockerCommandLineCodeExecutor` provides the recommended security baseline with `auto_remove=True` and filesystem isolation.
- Implement an **`approval_func`** callback to programmatically vet code before execution, preventing unauthorized operations.
- Configure **`work_dir`**, **`timeout`**, and **`extra_volumes`** explicitly to minimize attack surface and prevent resource exhaustion.
- Reference the source files in [`autogen_agentchat/agents/_code_executor_agent.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/agents/_code_executor_agent.py) and [`autogen_ext/code_executors/docker/_docker_code_executor.py`](https://github.com/microsoft/autogen/blob/main/autogen_ext/code_executors/docker/_docker_code_executor.py) to customize the secure execution pipeline.

## Frequently Asked Questions

### What is the difference between CodeExecutorAgent and a regular AssistantAgent?

The `CodeExecutorAgent` is specifically designed to extract markdown code blocks from messages and execute them in a sandboxed environment, whereas a standard `AssistantAgent` focuses on conversational responses without built-in code execution capabilities. The `CodeExecutorAgent` implements a dedicated execution-reflection loop with approval gates that standard agents lack.

### Why should I use DockerCommandLineCodeExecutor instead of the local executor?

You should use `DockerCommandLineCodeExecutor` because it provides OS-level isolation through containerization, automatically removes containers after execution with `auto_remove=True`, and restricts filesystem access via volume mounts. The local executor (`LocalCommandLineCodeExecutor`) runs code directly on your host machine and should only be used for debugging trusted code, as it offers no protection against malicious operations.

### How do I implement a custom approval function for CodeExecutorAgent?

Implement a callable that accepts an `ApprovalRequest` object and returns an `ApprovalResponse` with `approved` (boolean) and `reason` (string) fields. You can define either a synchronous function (`SyncApprovalFunc`) or asynchronous coroutine (`AsyncApprovalFunc`). In your implementation, inspect the `request.code` string to enforce security policies—such as whitelisting specific functions or blocking imports—before returning the approval decision.

### What security settings should I configure to prevent resource exhaustion?

Configure the **`timeout`** parameter (default 60 seconds) to limit execution time and prevent runaway processes. Set **`delete_tmp_files=True`** to ensure temporary source files are removed after execution. When using the Docker executor, explicitly define **`work_dir`** and avoid overly permissive **`extra_volumes`** to minimize filesystem exposure. Additionally, ensure **`stop_container`** is enabled to guarantee container cleanup when the executor closes.