Execution environment

freeact uses ipybox as its code execution environment, providing a secure Docker-based IPython runtime. You can either create a custom Docker image with your specific requirements or use prebuilt Docker images.

Custom Docker image

To build a custom ipybox Docker image with freeact-skills pre-installed, create a dependencies.txt file:

dependencies.txt

freeact-skills = {version = "*", extras = ["all"]}
# Add additional dependencies here if needed

Note

dependencies.txt must follow the Poetry dependency specification format.

Then build the ipybox Docker image referencing the dependencies file:

python -m ipybox build -t gradion-ai/ipybox:custom -d dependencies.txt

To use the image, reference it in CodeExecutionContainer when creating an ipybox Docker container. Use the env argument to set any API keys required by the pre-installed skills.

Prebuilt Docker images

We provide prebuilt Docker images with variants minimal, basic, and example. These variants have the following dependencies installed:

• ghcr.io/gradion-ai/ipybox:minimal:

  docker/dependencies-minimal.txt

  freeact-skills = {version = "0.0.8", extras = ["search-google", "search-perplexity"]}
  

• ghcr.io/gradion-ai/ipybox:basic:

  docker/dependencies-basic.txt

  freeact-skills = {version = "0.0.8", extras = ["search-google", "search-perplexity"]}
  matplotlib = "^3.10"
  numpy = "^2.2"
  pandas = "^2.2"
  sympy = "^1.13"
  

• ghcr.io/gradion-ai/ipybox:example, used for the tutorials:

  docker/dependencies-example.txt

  freeact-skills = {version = "0.0.8", extras = ["all"]}
  matplotlib = "^3.10"
  numpy = "^2.2"
  pandas = "^2.2"
  pygithub = "^2.5"
  sympy = "^1.13"
  

Note

Prebuilt images run with root privileges. For non-root execution, build a custom Docker image (and find further details in the ipybox installation guide).

Installing dependencies at runtime

In addition to letting an agent install required dependencies at runtime, you can install extra dependencies at runtime before launching an agent, which is useful for testing custom skills across agent sessions without rebuilding Docker images:

from freeact import execution_environment

async with execution_environment(ipybox_tag="ghcr.io/gradion-ai/ipybox:basic") as env:
    # Install the serpapi package in the current environment
    await env.executor.execute("!pip install serpapi")

    # Import skill modules that depend on serpapi
    skill_sources = await env.executor.get_module_sources(
        module_names=["my_skill_module_1", "my_skill_module_2"],
    )

    # Initialize agent with the new skills
    # ...

For production use, it's recommended to include frequently used dependencies in a custom Docker image instead.