calute.security.sandbox_backends.docker_backend

calute.security.sandbox_backends.docker_backend#

Docker-based sandbox backend for Calute.

Executes tool functions inside ephemeral Docker containers via the docker CLI. The function and its arguments are serialised with pickle, written to a temporary file that is bind-mounted into the container, executed by a small Python wrapper, and the result is deserialised from a second temporary file.

Resource limits (timeout, memory, network) from SandboxConfig are translated to docker run flags.

class calute.security.sandbox_backends.docker_backend.DockerSandboxBackend(sandbox_config: SandboxConfig)[source]#

Bases: object

Sandbox backend that runs tools inside ephemeral Docker containers.

Uses the docker CLI (not the Docker SDK) so there is no extra Python dependency. Requires Docker to be installed and the daemon to be running on the host.

The execution flow is:

  1. The callable and its arguments are serialised with pickle.

  2. The serialised payload is base64-encoded and piped as stdin into a docker run command.

  3. A small Python runner script inside the container deserialises the payload, executes the function, and writes the result (or error) back to stdout as base64-encoded pickle.

  4. The host deserialises the result and returns it to the caller.

Resource limits (timeout, memory, network) from SandboxConfig are translated to docker run flags.

_config#

The SandboxConfig governing timeout, memory limits, network access, and working directory.

_backend_config#

The SandboxBackendConfig with Docker-specific settings such as image name, mount paths, and environment variables.

execute(tool_name: str, func: Callable, arguments: dict) → Any[source]#

Execute a callable with arguments inside an ephemeral Docker container.

The function and its arguments are serialised with pickle, base64-encoded, and piped into a minimal Python runner script inside the container. The result is deserialised from the container’s stdout.

Parameters

  • tool_name – The name of the tool being executed, used for logging and error messages.

  • func – The callable to execute within the Docker container. Must be picklable.

  • arguments – Keyword arguments to pass to func. All values must be picklable.

Returns

The return value of func(**arguments) as produced inside the container.

Raises

RuntimeError – If the Docker command times out, the container returns a non-zero exit code, the result cannot be deserialised, or the function raised an exception inside the container.

get_capabilities() → dict[str, Any][source]#

Return a dictionary describing the Docker backend’s capabilities and status.

Returns

  • "backend": Always "docker".

  • "available": Whether Docker is currently available.

  • "image": The container image used for execution.

  • "network_access": Whether sandbox has network access.

  • "memory_limit_mb": Memory limit in megabytes.

  • "timeout": Execution timeout in seconds.

Return type

A dict with the following keys

is_available() → bool[source]#

Check whether Docker is installed and the daemon is running.

Runs docker info with a 10-second timeout to verify that the docker CLI is on the PATH and the daemon is responsive.

Returns

True if the docker CLI is accessible and the daemon responded successfully, False otherwise (including when Docker is not installed, the daemon is stopped, or the command times out).

Contents