ExecutionContainer

DEFAULT_TAG `module-attribute`

DEFAULT_TAG = 'gradion-ai/ipybox'

ExecutionContainer

ExecutionContainer(
    tag: str = DEFAULT_TAG,
    binds: dict[str, str] | None = None,
    env: dict[str, str] | None = None,
    executor_port: int | None = None,
    resource_port: int | None = None,
    port_allocation_timeout: float = 10,
    show_pull_progress: bool = True,
)

Context manager for the lifecycle of a code execution Docker container. A code execution container provides:

a Jupyter Kernel Gateway for stateful code execution in IPython kernels. Clients connect to it via ExecutionClient on the container's executor host port.
a resource server for downloading Python module sources and registering MCP servers. Clients connect to it via ResourceClient on the container's resource host port.

Parameters:

Name	Type	Description	Default
`tag`	`str`	Name and optionally tag of the `ipybox` Docker image to use (format: `name:tag`)	`DEFAULT_TAG`
`binds`	`dict[str, str] \| None`	A dictionary mapping host paths to container paths for bind mounts. Host paths may be relative or absolute. Container paths must be relative and are created as subdirectories of `/app` in the container.	`None`
`env`	`dict[str, str] \| None`	Environment variables to set in the container	`None`
`executor_port`	`int \| None`	Host port for the container's executor port. A random port is allocated if not specified.	`None`
`resource_port`	`int \| None`	Host port for the container's resource port. A random port is allocated if not specified.	`None`
`port_allocation_timeout`	`float`	Maximum time in seconds to wait for port random allocation.	`10`
`show_pull_progress`	`bool`	Whether to show progress when pulling the Docker image.	`True`

Source code in ipybox/container.py

def __init__(
    self,
    tag: str = DEFAULT_TAG,
    binds: dict[str, str] | None = None,
    env: dict[str, str] | None = None,
    executor_port: int | None = None,
    resource_port: int | None = None,
    port_allocation_timeout: float = 10,
    show_pull_progress: bool = True,
):
    self.tag = tag
    self.binds = binds or {}
    self.env = env or {}
    self.show_pull_progress = show_pull_progress

    self._docker = None
    self._container = None
    self._executor_port = executor_port
    self._resource_port = resource_port
    self._port_allocation_timeout = port_allocation_timeout

executor_port `property`

executor_port: int

The host port of the container's executor port. Either an application-defined executor_port via the constructor or a dynamically allocated random port.

Raises:

Type	Description
`RuntimeError`	If the container is not running and an application-defined port was not provided.

resource_port `property`

resource_port: int

The host port of the container's resource port. Either an application-defined resource_port via the constructor or a dynamically allocated random port.

Raises:

Type	Description
`RuntimeError`	If the container is not running and an application-defined port was not provided.

kill `async`

kill()

Kills and removes the current code execution Docker container.

Source code in ipybox/container.py

async def kill(self):
    """Kills and removes the current code execution Docker container."""
    if self._container:
        await self._container.kill()

    if self._docker:
        await self._docker.close()

run `async`

run()

Creates and starts a code execution Docker container.

Source code in ipybox/container.py

async def run(self):
    """Creates and starts a code execution Docker container."""
    self._docker = Docker()
    await self._run()

ExecutionContainer

DEFAULT_TAG module-attribute