smolagents' Docker executor on kosa8

01What was tested

Tested with kosa8 v0.9.10, on 15 October 2026 on an Apple silicon Mac (macOS, arm64), with the released v0.9.10 binaries and guest image, with smolagents 1.26.0, docker (the Python SDK) 7.2.0 and Python 3.12.13. No LLM or API key was used: the executor was called directly.

• Worked: DockerExecutor with its defaults built its jupyter-kernel image through the Docker API (POST /build, FROM python:3.12-bullseye plus pip install), started the kernel gateway container on 127.0.0.1:8888, ran code, returned its output and removed the container on cleanup().
• No longer needed: building the image with kosa8 build first and passing build_new_image=False. That was the workaround before kosa8 served POST /build.

02Set it up

Start the daemon and point the Docker SDK at kosa8:

03Run code in it

Nothing here is specific to kosa8. On the first run the executor builds its image, which pulls packages from PyPI, so it needs network access.

from smolagents.monitoring import AgentLogger, LogLevel
from smolagents.remote_executors import DockerExecutor
 
executor = DockerExecutor(additional_imports=[], logger=AgentLogger(level=LogLevel.INFO))
try:
    out = executor.run_code_raise_errors(
        "import platform\n"
        "x = sum(range(10))\n"
        "print('kernel on', platform.machine())\n"
        "x * 2"
    )
    print(out.logs.strip(), out.output)
finally:
    executor.cleanup()

python run_in_kosa8.py
Starting container on 127.0.0.1:8888...
kernel on aarch64 90
Container cleanup completed

With an agent, use the executor type as usual:

from smolagents import CodeAgent
 
agent = CodeAgent(
    tools=[],
    model=model,  # any smolagents model
    executor_type="docker",
)

04Limits

• The kernel port is published on the host. smolagents publishes the kernel gateway on 127.0.0.1:8888 by default. If that port is in use, pass port (directly or in executor_kwargs).
• Host folders only from allowed directories. container_run_kwargs with volumes works only for folders below one named with kosa8 daemon start --allow-mount DIR (add :rw for write access).
• additional_imports are installed with pip at start, so the container needs network access to PyPI.
• Only the executor was tested. A run with a real model was not part of this test.