Skip to content
Nappai Documentation

DockerSandbox

The DockerSandbox component acts as a safe, isolated workspace for your automation tasks. Think of it as a temporary, secure “laboratory” where your AI agents and scripts can run code without affecting the rest of your system or data. It automatically handles the setup, execution, and cleanup of a secure environment, allowing you to focus on what the task should accomplish rather than worrying about technical setup.

How it Works

When you use this component, it creates a temporary, isolated container based on Docker. It safely injects your code or processes into this container, runs them with built-in safety limits (like memory and time restrictions), and monitors the process in real-time. Once the task finishes, the component automatically captures any results or logs, measures how much system resources were used, and cleanly shuts down the container to keep your system tidy and efficient.

Connection & Credentials

This component requires configuring a credential in the Nappai panel before interacting with the external service:

  1. Go to the Credentials section in your Nappai panel.
  2. Create a new credential of the type specified for this component and fill in the required fields (API Keys, tokens, etc.).
  3. In your workflow, select the saved credential in the Credential input field of this node.

Inputs

This component does not require manual input configuration. It is designed to work out-of-the-box by inheriting all necessary settings automatically. You only need to ensure that the required credential is properly configured and selected as described in the “Connection & Credentials” section above.

Outputs

Once the task finishes running inside the sandbox, this component provides a summary of the execution. You will receive a structured report that tells you whether the process succeeded or failed, any text output generated by the script, any error messages, and resource usage details (like CPU and memory consumption). This information can be passed to other components for logging, reporting, or further data processing.

Output Data Example (JSON)json

{ “execution_status”: “success”, “stdout”: “Process completed successfully. Data processed: 150 records.”, “stderr”: "", “resource_usage”: { “cpu_percent”: 12.5, “memory_mb”: 256, “duration_seconds”: 4.2 }, “container_metadata”: { “id”: “container_8a3f2b”, “created_at”: “2024-05-20T10:00:00Z” } }

Connectivity

In a typical Nappai workflow, the DockerSandbox is usually connected to AI agent components, data processing nodes, or script execution tools that need a secure place to run. After execution, its output is typically routed to logging components, data viewers, or reporting dashboards. This makes logical sense because it provides the execution environment, while connected nodes either trigger the task or consume the results for further action.

Usage Example

Imagine you have an AI agent that needs to analyze a sensitive dataset. Instead of running the analysis directly in your main workflow, you connect the agent to a DockerSandbox component. The sandbox securely runs the analysis script, keeps your main data isolated and safe, and returns a summary report along with the execution metrics. You can then connect the sandbox’s output to a data visualization node to display the results on your dashboard.

Tips and Best Practices

  • Keep your sandbox credentials updated and securely stored to ensure uninterrupted automation.
  • Monitor the execution metrics (CPU, memory, and time) to ensure your tasks are running efficiently.
  • Use this component for tasks that require isolation or security, but avoid placing extremely long-running or heavy resource tasks in the sandbox if they exceed Docker’s default limits.
  • Test new scripts in a safe environment before connecting them to critical data pipelines.

Security Considerations

The DockerSandbox is designed with security as a priority. It isolates code execution in a separate container, preventing potential errors or malicious code from affecting your main system. It enforces resource limits to prevent system overload, and requires secure mTLS credentials to ensure that only authorized connections can interact with the Docker environment. Always store your credentials carefully and only grant access to trusted workflows.