kosa8

kosa8 / Guides

Guide · Updated 2026-10-31

How do I make smolagents code execution secure locally?

By default smolagents runs a CodeAgent's Python in your own process through its LocalPythonExecutor, and its docs warn that no local Python sandbox can ever be completely secure. Set executor_type="docker" and point the Docker SDK at kosa8 with DOCKER_HOST, and the generated code runs in a container inside a microVM on your own machine, with no cloud account. kosa8 tested smolagents' DockerExecutor with its defaults, including the image it builds itself.

01Steps

  1. Install kosa8. On an Apple silicon Mac or x86-64 Linux:

  2. Start the daemon and point Docker clients at kosa8. kosa8 serves a Docker-compatible API on a local socket. The Docker SDK for Python reads DOCKER_HOST.

  3. Install smolagents with the Docker extra. kosa8 tested smolagents 1.26.0 with docker 7.2.0 and Python 3.12.

  4. Check the executor on its own. Nothing here is specific to kosa8. On the first run the executor builds its Jupyter kernel image through the Docker API, which pulls packages from PyPI, so it needs network access.

    run_in_kosa8.py
    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\nx = sum(range(10))\nprint('kernel on', platform.machine())\nx * 2"
    )
    print(out.logs.strip(), out.output)
finally:
    executor.cleanup()
    output
    python run_in_kosa8.py
Starting container on 127.0.0.1:8888...
kernel on aarch64 90
Container cleanup completed

  5. Use the Docker executor in your agent. One argument changes. Using the agent as a context manager cleans the container up when the run ends.

    agent.py
    from smolagents import CodeAgent
 
with CodeAgent(tools=[], model=model, executor_type="docker") as agent:  # any smolagents model
    agent.run("What is the 20th Fibonacci number?")

02Is the smolagents local Python executor safe?

It is safer than plain Python, but not a security boundary. LocalPythonExecutor walks the code's syntax tree, refuses imports you have not authorised, blocks submodule access such as random._os, and caps loop iterations. The smolagents docs still warn that no local Python sandbox can ever be completely secure, and that a determined attacker or a fine-tuned malicious LLM may find a way through an authorised package.

Their example: allow Pillow and the code can write thousands of large images until the disk is full. The docs recommend a remote or container sandbox for high-security use and for less trusted models.

03Which executor_type options does smolagents have?

The default is the local executor. The secure code execution guide documents executor_type="blaxel", "e2b", "modal" and "docker". Each runs only the generated code snippets in the sandbox while the agent and model calls stay in your process, which keeps API keys out of the sandbox but does not support managed multi-agent setups.

The other approach in the same guide runs the whole agent system inside a sandbox. It supports multi-agents, but the sandbox then needs your model credentials.

04What changes when the smolagents Docker executor runs on kosa8?

Your code does not change. The kernel container runs in kosa8's shared engine, an always-warm virtual machine with its own kernel, instead of directly on your host's kernel or Docker Desktop's VM. smolagents still publishes the kernel gateway on 127.0.0.1:8888.

From kosa8's test notes: if port 8888 is taken, pass port (directly or in executor_kwargs); additional_imports are installed with pip at start, so the container needs PyPI; and container_run_kwargs volumes work only below a folder named with kosa8 daemon start --allow-mount DIR. Containers created through kosa8's Docker-compatible API run in its shared engine: one always-warm virtual machine, separated from your computer by a VM boundary and from other containers in it by ordinary container isolation. For a machine of its own per task, with its own egress rules and checkpoints, use kosa8 sandbox directly, as in the LangChain guide.

05Other options

  • executor_type="e2b", "modal" or "blaxel". Hosted sandboxes built into smolagents, a fit when you want no local setup and accept a cloud account.
  • executor_type="docker" with Docker. The same executor on Docker Desktop or Docker Engine. The smolagents docs suggest memory and CPU limits, dropped capabilities and no unneeded network.
  • The whole agent in a sandbox. Required for managed multi-agent setups, at the cost of passing credentials in.
  • gVisor. On Linux, the runsc runtime adds a user-space kernel under the Docker executor's container.
  • LocalPythonExecutor with a short import list. Fine for well-known models on trusted tasks, as smolagents itself describes.

06Sources

Updated 2026-10-31