Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/swe-agent/mini-swe-agent/llms.txt

Use this file to discover all available pages before exploring further.

An environment is responsible for executing shell commands and returning their output. Every environment exposes the same minimal interface: an execute(action, cwd, *, timeout) method that accepts an action dict (with a "command" key) and returns a dict with output, returncode, and exception_info keys. Environments are selected via the environment_class key in a YAML config or by importing the class directly in Python. The helper get_environment from minisweagent.environments can instantiate any environment from a plain dict. 
from minisweagent.environments import get_environment

env = get_environment({"environment_class": "docker", "image": "python:3.12-slim"})
The string shortcuts accepted by get_environment are: local, docker, singularity, bubblewrap, contree, swerex_docker, swerex_modal.

​
LocalEnvironment

Executes commands directly on the host machine via subprocess.run. No container or sandbox is involved. Suitable for development, CI, or any context where the host filesystem is the workspace. 
from minisweagent.environments.local import LocalEnvironment
​
cwd
str
default:"\"\""
Working directory for all commands. Defaults to the current working directory of the Python process when left empty.
​
env
dict[str, str]
default:"{}"
Extra environment variables merged into the process environment via os.environ | config.env. Host variables not in this dict are still inherited.
​
timeout
int
default:"30"
Per-command timeout in seconds. Raises a subprocess.TimeoutExpired exception (caught and returned as an error dict) when exceeded.
YAML example 
environment_class: local
cwd: /repo
timeout: 60

​
DockerEnvironment

Starts a long-lived Docker container at construction time and runs each command via docker exec. The container is removed when the environment object is garbage-collected or cleanup() is called explicitly. 
from minisweagent.environments.docker import DockerEnvironment
​
image
str
required
Docker image to run. The image is pulled if not present locally. Pull timeout is controlled by pull_timeout.
​
cwd
str
default:"\"/\""
Working directory inside the container.
​
env
dict[str, str]
default:"{}"
Environment variables set inside the container. Takes precedence over forward_env values if there is a conflict.
​
forward_env
list[str]
default:"[]"
Names of host environment variables to forward into the container. Variables are only forwarded if they are set on the host.
​
timeout
int
default:"30"
Per-command timeout in seconds for docker exec calls.
​
executable
str
default:"\"docker\""
Path to the container runtime executable. Override via the MSWEA_DOCKER_EXECUTABLE environment variable or this config field. Useful for Podman or other Docker-compatible runtimes.
​
run_args
list[str]
default:"[\"--rm\"]"
Additional arguments appended to docker run. The default --rm removes the container after it stops.
​
container_timeout
str
default:"\"2h\""
Maximum duration the container is kept alive, expressed as a sleep-compatible duration string (e.g. "2h", "30m").
​
pull_timeout
int
default:"120"
Timeout in seconds for the initial image pull.
​
interpreter
list[str]
default:"[\"bash\", \"-lc\"]"
Interpreter used to run each command. The command string is appended as the final argument. Override to change shell flags (e.g. remove -l to skip login-shell initialisation) or use a different interpreter such as Python.
YAML example 
environment_class: docker
image: swebench/sweb.eval.x86_64.astropy_2__astropy__5.1:latest
cwd: /repo
timeout: 120
forward_env:
  - GITHUB_TOKEN

​
SingularityEnvironment

Runs each command inside a Singularity/Apptainer container. At construction time the image is converted to a writable sandbox directory in the system temp folder. The sandbox is cleaned up when the object is destroyed. 
from minisweagent.environments.singularity import SingularityEnvironment
​
image
str
required
Singularity image URI or path (e.g. docker://python:3.12-slim or a local .sif file path).
​
cwd
str
default:"\"/\""
Working directory inside the container for command execution.
​
env
dict[str, str]
default:"{}"
Environment variables set inside the container via --env KEY=VALUE.
​
forward_env
list[str]
default:"[]"
Host environment variable names to forward into the container. Only forwarded when set on the host.
​
timeout
int
default:"30"
Per-command timeout in seconds.
​
executable
str
default:"\"singularity\""
Path to the Singularity/Apptainer executable. Override via MSWEA_SINGULARITY_EXECUTABLE.
​
sandbox_build_retries
int
default:"3"
Number of retry attempts for the singularity build --sandbox step, which can occasionally fail on network-backed images.
​
global_args
list[str]
default:"[\"--quiet\"]"
Arguments inserted before the subcommand (e.g. --quiet, --debug).
​
exec_args
list[str]
default:"[\"--contain\", \"--cleanenv\", \"--fakeroot\"]"
Arguments appended to singularity exec. The defaults isolate the container from the host environment and run with a fakeroot.
YAML example 
environment_class: singularity
image: docker://python:3.12-slim
cwd: /workspace
timeout: 60

​
BubblewrapEnvironment

Runs commands inside an unprivileged Linux sandbox created by Bubblewrap (bwrap). A fresh temporary working directory is created for each environment instance and cleaned up on destruction. Note: This environment is experimental and Linux-only. 
from minisweagent.environments.extra.bubblewrap import BubblewrapEnvironment
​
cwd
str
default:"\"\""
Working directory inside the sandbox. Defaults to the auto-generated temporary directory for this environment instance.
​
env
dict[str, str]
default:"{}"
Environment variables to set inside the sandbox via --setenv.
​
timeout
int
default:"30"
Per-command timeout in seconds.
​
executable
str
default:"\"bwrap\""
Path to the Bubblewrap executable. Override via MSWEA_BUBBLEWRAP_EXECUTABLE.
​
wrapper_args
list[str]
Full list of arguments passed to bwrap before the command. The default mounts /usr, /bin, /lib, /lib64, /etc as read-only, creates a tmpfs at /tmp, and sets a restricted PATH. Override this list to customise the sandbox layout.
YAML example 
environment_class: bubblewrap
timeout: 30

​
ContreeEnvironment

Runs commands inside a ConTree container managed via the contree-sdk Python package. Requires the optional dependency: pip install contree-sdk. 
from minisweagent.environments.extra.contree import ContreeEnvironment
​
contree_config
ContreeConfig | dict
required
Configuration for the ConTree client. Accepts a ContreeConfig object or a plain dict that will be converted to one.
​
image
str
required
OCI image reference to run (e.g. python:3.12-slim).
​
image_tag
str | None
default:"None"
If set, the image is pulled by this tag. Falls back to importing by the image reference and tagging it.
​
cwd
str
default:"\"/\""
Working directory inside the container.
​
cwd_auto_create
bool
default:"true"
When true, runs mkdir -p <cwd> before the first command.
​
env
dict[str, str]
default:"{}"
Environment variables set in the container. Takes precedence over forward_env on conflict.
​
forward_env
list[str]
default:"[]"
Host environment variable names to forward into the container.
​
interpreter
list[str]
default:"[\"bash\", \"-c\"]"
Interpreter used to run commands.
​
timeout
int
default:"100"
Per-command timeout in seconds.
​
import_username
str | None
default:"None"
Registry username used when importing a private image.
​
import_password
str | None
default:"None"
Registry password used when importing a private image.

​
SwerexDockerEnvironment

Runs commands in a Docker container managed by SWE-ReX. Requires the optional dependency: pip install swerex. 
from minisweagent.environments.extra.swerex_docker import SwerexDockerEnvironment
​
image
str
required
Docker image to deploy.
​
cwd
str
default:"\"/\""
Default working directory for command execution.
​
timeout
int
default:"30"
Per-command timeout in seconds.
​
deployment_extra_kwargs
dict
default:"{}"
Additional keyword arguments forwarded to swerex.deployment.docker.DockerDeployment.
YAML example 
environment_class: swerex_docker
image: python:3.12-slim
cwd: /workspace
timeout: 60

​
SwerexModalEnvironment

Runs commands inside a Modal serverless sandbox via SWE-ReX. Useful for large-scale parallel evaluations and training workloads. Requires the optional dependencies: pip install swerex modal. 
from minisweagent.environments.extra.swerex_modal import SwerexModalEnvironment
​
image
str
required
Image to use for the Modal deployment. Accepts:
  • Docker Hub image name (e.g. python:3.11-slim)
  • ECR image URI
  • Path to a Dockerfile
​
cwd
str
default:"\"/\""
Default working directory inside the sandbox.
​
timeout
int
default:"30"
Per-command execution timeout in seconds.
​
env
dict[str, str]
default:"{}"
Environment variables passed to each command execution.
​
startup_timeout
float
default:"60.0"
Seconds to wait for the Modal sandbox runtime to become ready.
​
runtime_timeout
float
default:"3600.0"
How long the Modal sandbox may stay alive in total (seconds).
​
deployment_timeout
float
default:"3600.0"
Overall deployment timeout in seconds.
​
install_pipx
bool
default:"true"
Whether to install pipx in the container. Required by the SWE-ReX runtime.
​
modal_sandbox_kwargs
dict
default:"{}"
Additional keyword arguments forwarded directly to modal.Sandbox.create.
YAML example 
environment_class: swerex_modal
image: python:3.12-slim
cwd: /workspace
startup_timeout: 120.0

​
Selecting an environment via CLI

When using the mini CLI, pass --environment-class (or set it in your YAML config): 
mini --environment-class docker
In a YAML config file: 
environment:
  environment_class: docker
  image: python:3.12-slim
  cwd: /repo
  timeout: 120

Build docs developers (and LLMs) love

Get started for freeTalk to us