hythzx/data-analysis-execution-worker repository overview

⁠data-analysis-execution-worker

data-analysis-execution-worker is the isolated code execution service for Data Analysis Agent.

It sits between the Agent and Docker Engine and is responsible for executing AI-generated or Skill-provided Python code inside short-lived, resource-constrained Docker sandbox containers.

The Execution Worker itself does not perform data analysis. Instead, it manages the lifecycle of isolated runtime containers, applies execution policies, collects results and artifacts, handles timeouts and cancellation, and returns structured execution results to the Agent.

⁠Architecture

User
  │
  ▼
Data Analysis Agent
  │
  │ Execution API
  ▼
data-analysis-execution-worker
  │
  │ docker run
  ▼
Docker Engine
  │
  ▼
data-analysis-python-runtime
  │
  ├── Python
  ├── pandas / NumPy / SciPy
  ├── scikit-learn
  ├── matplotlib
  ├── PyArrow
  └── openpyxl
       │
       ▼
  Results / Artifacts

The separation between the Agent, Execution Worker, and Python Runtime allows generated code to run outside the main Agent process.

⁠Responsibilities

The Execution Worker provides the execution control plane for Data Analysis Agent.

Its primary responsibilities include:

• Accepting code execution requests from the Agent
• Creating an isolated workspace for each execution
• Starting temporary Docker sandbox containers
• Enforcing CPU, memory, process, and timeout limits
• Disabling network access inside execution containers
• Running containers with a read-only root filesystem
• Dropping Linux capabilities
• Preventing privilege escalation
• Executing containers as a non-root user
• Collecting stdout and stderr
• Reading structured execution results
• Collecting generated artifacts
• Terminating timed-out or cancelled executions
• Removing temporary containers and execution workspaces

⁠Execution Model

Each execution gets its own temporary workspace.

Conceptually:

execution-workspace/
├── input/
│   └── request.json
├── code/
│   └── main.py
└── output/
    ├── result.json
    └── artifacts/

The worker prepares this workspace and starts a sandbox container using the configured Python runtime image.

Inside the container, the generated program is executed as:

python /workspace/code/main.py

After execution, the worker collects:

exit status
structured result
stdout
stderr
artifacts
execution duration
timestamps

The sandbox container is then removed.

Execution containers are intentionally ephemeral.

⁠Sandbox Security

Generated code should never be treated as trusted code.

For that reason, data-analysis-execution-worker launches runtime containers with several isolation controls.

A typical execution uses protections equivalent to:

--network none
--read-only
--cap-drop ALL
--security-opt no-new-privileges
--memory <limit>
--cpus <limit>
--pids-limit <limit>
--user 10001:10001

A small writable /tmp filesystem is provided through tmpfs.

The runtime therefore has:

Network access       Disabled
Root filesystem      Read-only
Linux capabilities   Dropped
Privilege escalation Disabled
Runtime user         Non-root
Memory               Limited
CPU                  Limited
Processes            Limited
Execution time       Limited

This reduces the impact of erroneous or malicious generated code.

⁠Supported Execution Policies

The worker can apply different policies depending on the execution type.

For example:

Dynamic Python
  timeout: 30 seconds
  memory: 1024 MB
  CPU: 1
  process limit: 128

Skill Script
  timeout: 120 seconds
  memory: 2048 MB
  CPU: 1
  process limit: 128

These values are configurable through environment variables.

Requested execution timeouts are constrained by the maximum policy configured on the worker.

⁠Python Runtime

The worker is designed to work with the companion image:

data-analysis-python-runtime

The default runtime contains common data-analysis libraries including:

pandas
numpy
scipy
matplotlib
pyarrow
openpyxl
scikit-learn

The runtime image can be replaced through configuration, allowing specialized environments to be introduced later without modifying the Agent itself.

For example:

data-analysis-python-runtime
data-analysis-ml-runtime
data-analysis-geo-runtime

⁠Artifacts

Python executions can generate artifacts such as:

PNG / JPEG charts
CSV datasets
JSON results
Excel workbooks (.xlsx)

Artifacts are collected from:

/workspace/output/artifacts

and returned to the Agent as part of the execution result.

The worker applies limits to artifact size to prevent an execution from returning unbounded amounts of data.

⁠Running with Docker

The Execution Worker needs access to a Docker Engine because it creates sandbox containers dynamically.

Example:

docker run -d \
  --name data-analysis-execution-worker \
  -p 3100:3100 \
  -e EXECUTION_WORKER_HOST=0.0.0.0 \
  -e EXECUTION_WORKER_PORT=3100 \
  -e EXECUTION_PYTHON_IMAGE=<dockerhub-user>/data-analysis-python-runtime:latest \
  -v /var/run/docker.sock:/var/run/docker.sock \
  <dockerhub-user>/data-analysis-execution-worker:latest

The corresponding Python runtime image must also be available to the Docker Engine:

docker pull <dockerhub-user>/data-analysis-python-runtime:latest

⁠Docker Compose

A typical deployment looks like:

services:
  execution-worker:
    image: <dockerhub-user>/data-analysis-execution-worker:latest

    environment:
      EXECUTION_WORKER_HOST: 0.0.0.0
      EXECUTION_WORKER_PORT: 3100

      EXECUTION_PYTHON_IMAGE: <dockerhub-user>/data-analysis-python-runtime:latest

      EXECUTION_DYNAMIC_TIMEOUT_MS: 30000
      EXECUTION_SKILL_TIMEOUT_MS: 120000

      EXECUTION_DYNAMIC_MEMORY_MB: 1024
      EXECUTION_SKILL_MEMORY_MB: 2048

      EXECUTION_DYNAMIC_CPUS: 1
      EXECUTION_SKILL_CPUS: 1

      EXECUTION_PIDS_LIMIT: 128

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /tmp/data-analysis-agent-executions:/tmp/data-analysis-agent-executions

    ports:
      - "3100:3100"

The Agent can then connect to the worker using:

EXECUTION_WORKER_URL=http://execution-worker:3100

⁠Configuration

Important configuration options include:

EXECUTION_WORKER_HOST
EXECUTION_WORKER_PORT
EXECUTION_WORK_ROOT

EXECUTION_PYTHON_IMAGE

EXECUTION_DYNAMIC_TIMEOUT_MS
EXECUTION_SKILL_TIMEOUT_MS

EXECUTION_DYNAMIC_MEMORY_MB
EXECUTION_SKILL_MEMORY_MB

EXECUTION_DYNAMIC_CPUS
EXECUTION_SKILL_CPUS

EXECUTION_PIDS_LIMIT
EXECUTION_MAX_CODE_BYTES
EXECUTION_MAX_INPUT_BYTES

These settings allow operators to control how much compute and data an individual execution can consume.

⁠Important Security Notice

The Execution Worker requires access to Docker Engine in order to create sandbox containers.

A common deployment mounts:

/var/run/docker.sock:/var/run/docker.sock

Access to the Docker socket is highly privileged and should effectively be treated as host-level control.

Therefore:

Do not expose the Execution Worker directly to the public Internet.

Recommended architecture:

Internet
   │
   ▼
Application / API
   │
   ▼
Data Analysis Agent
   │
   │ private network
   ▼
Execution Worker
   │
   ▼
Docker Engine

The worker should only be reachable from trusted internal services.

For stronger production isolation, consider running execution workloads on a dedicated Docker host, VM, container runtime service, or other isolated compute environment instead of exposing the primary application host's Docker socket.

⁠Why a Separate Execution Worker?

Running generated Python directly inside the Agent process would couple untrusted computation with the application control plane.

The worker architecture separates these concerns:

Agent
  → reasoning
  → tool orchestration
  → conversation
  → session management

Execution Worker
  → execution lifecycle
  → resource policies
  → timeout / cancellation
  → sandbox management

Python Runtime
  → actual data computation
  → statistics
  → machine learning
  → visualization
  → artifact generation

This separation makes the system easier to secure, scale, monitor, and extend.

⁠Related Images

The complete Data Analysis Agent stack consists of:

data-analysis-agent
    Main Agent service and API

data-analysis-execution-worker
    Isolated execution orchestration service

data-analysis-python-runtime
    Python data-analysis sandbox runtime

data-analysis-agent-web
    Web frontend

Together they provide an Agentic data-analysis environment where the model can reason about a problem, query data, execute analytical code in an isolated environment, generate artifacts, and return the final analysis to the user.

⁠Versioning

For production deployments, prefer a fixed version tag instead of latest.

For example:

docker pull <dockerhub-user>/data-analysis-execution-worker:1.0.0

Use latest for development or environments where automatically following the newest build is acceptable.

⁠Project

Part of the Data Analysis Agent project — an agentic data-analysis platform built around isolated tools, Skills, safe data access, and sandboxed code execution.