DOCSEARCHbyAlgolia
Submit Docs

SWE-ReX

repository·main·Indexed 20 days ago

https://github.com/swe-agent/swe-rex

A runtime interface for interacting with sandboxed shell environments, allowing AI agents to execute commands across local machines, Docker containers, AWS Fargate, or Modal using a unified API. It supports shell session interaction, interactive CLI tools like ipython and gdb, and parallel execution of multiple concurrent sessions.

Tokens
10.3K
Snippets
38
Records
53
Agent score
68%

What's inside swe-rex

  1. What is SWE-ReX

    main

    SWE-ReX is a runtime interface designed for interacting with sandboxed shell environments. It allows AI agents to execute commands across various environments—including local machines, Docker containers, AWS remote machines, or Modal—using a unified interface. This abstraction ensures that the agent's core logic remains decoupled from the underlying infrastructure.

    Key capabilities include:

    • Shell Session Interaction: Automatically detects command completion, extracts output and exit codes, and returns them to the agent.
    • Interactive Tool Support: Enables agents to use interactive CLI tools such as ipython or gdb within the shell.
    • Parallelism: Supports managing multiple concurrent shell sessions, allowing an agent to interact with different tools (e.g., a shell, an ipython session, and a gdb session) simultaneously.
    • Scalability: Designed to support massively parallel agent runs for large-scale benchmarking and evaluation.

  2. Using Runtime sessions with run_in_session

    main

    The Runtime abstraction (implemented by both RemoteRuntime and LocalRuntime) provides methods for file I/O and command execution. The most critical method for complex workflows is run_in_session.

    run_in_session allows you to execute commands within an existing shell session or an interactive tool. This enables stateful interactions (like keeping a shell environment alive) and allows you to run multiple sessions in parallel to execute different commands or tools simultaneously.

  3. How SWE-ReX architecture works

    main

    SWE-ReX operates through a layered architecture that separates deployment management from environment interaction:

    1. Deployment: You start by using a Deployment class (e.g., for Docker or AWS) to provision your environment. This abstracts away manual infrastructure management.
    2. RemoteRuntime: Once a deployment is active, you are provided with a RemoteRuntime instance. This is your primary interface for interacting with the remote environment (starting shells, reading/writing files, executing commands).
    3. Server & LocalRuntime: Inside the remote environment, a FastAPI Server acts as a bridge. It receives requests from the RemoteRuntime and forwards them to a LocalRuntime.
    4. Interchangeability: The LocalRuntime shares the exact same interface as RemoteRuntime. If you are running code in a local sandbox, you can use LocalRuntime directly. Exceptions from the LocalRuntime are transparently transferred to the RemoteRuntime, allowing for consistent error handling.

  4. Install swe-rex via pip

    main

    Install the latest stable release of swe-rex using pip. You can choose to include optional dependencies for specific environments like Modal or AWS Fargate.

    # Latest stable release
pip install swe-rex

# With modal support
pip install 'swe-rex[modal]'

# With fargate support
pip install 'swe-rex[fargate]'

# Development setup (includes all optional dependencies)
pip install 'swe-rex[dev]'

  5. Configure deployments using deployment configuration objects

    main

    Deployments in swerex are configured using specific configuration objects. To create a deployment, instantiate a configuration class (such as DockerDeploymentConfig) with the required parameters and call the .get_deployment() method. This returns a deployment instance ready for use.

    from swerex.deployment.config import DockerDeploymentConfig

# Initialize the configuration with specific parameters
config = DockerDeploymentConfig(image="python:3.11")

# Generate the deployment instance
deployment = config.get_deployment()

  6. Include the navigation footer in MkDocs pages

    main

    To add the navigation footer to your documentation pages, use the Jinja2-style include syntax. This ensures the footer (defined in docs/_footer.md) appears consistently across your site.

    Add the following line to the bottom of your Markdown files (e.g., docs/index.md, docs/usage.md):

    {% include-markdown "_footer.md" %}

    {% include-markdown "_footer.md" %}

  7. Run commands on Modal with ModalDeployment

    main

    Use ModalDeployment to execute commands in a remote sandbox on Modal. This is useful for highly scalable or specialized remote environments.

    Configuration Options:

    • image: The Docker image to use for the sandbox.
    • startup_timeout: Maximum time (in seconds) to wait for the deployment to start.
    • deployment_timeout: Maximum time (in seconds) before the deployment is killed.

    Example:

    from swerex.deployment.modal import ModalDeployment
import asyncio

async def run_modal_deployment():
    deployment = ModalDeployment(
        image="python:3.12",
        startup_timeout=60,
        deployment_timeout=3600,
    )
    await deployment.start()
    await deployment.is_alive()
    return deployment

deployment = asyncio.run(run_modal_deployment())
asyncio.run(run_some_stuff(deployment))
    from swerex.deployment.modal import ModalDeployment
import asyncio

async def run_modal_deployment():
    deployment = ModalDeployment(
        image="python:3.12",
        startup_timeout=60,
        deployment_timeout=3600,
    )
    await deployment.start()
    await deployment.is_alive()
    return deployment

deployment = asyncio.run(run_modal_deployment())
asyncio.run(run_some_stuff(deployment))

  8. Clean up AWS resources created by Fargate deployment

    main

    The Fargate deployment creates persistent AWS resources including ECS Clusters, Task Definitions, Security Groups, and IAM Roles. All these resources are tagged with origin=swe-rex-deployment-auto to allow for safe identification and removal.

    To prevent accumulating unused resources and incurring unnecessary costs, use the built-in teardown utility. This utility previews tagged resources, requests confirmation, and deletes them in the correct dependency order.

    Note: This deployment is currently in alpha stage and is subject to breaking changes. Running a new Fargate deployment will automatically recreate the necessary resources.

    python -m swerex.utils.aws_teardown

  9. Run commands locally with LocalDeployment

    main

    Use LocalDeployment to execute commands directly on your host machine.

    Warning: This runs commands without sandboxing. Do not execute destructive commands like rm -rf /.

    Key Workflow:

    1. Instantiate LocalDeployment().
    2. await deployment.start() to initialize the runtime.
    3. Use runtime.execute(Command(command=[...])) for one-off commands (similar to subprocess.run()).
    4. Use runtime.create_session(CreateBashSessionRequest()) to start a persistent bash session.
    5. Use runtime.run_in_session(BashAction(command="...")) to run commands within a session where environment state (like variables) persists.
    6. await deployment.stop() to clean up.

    Note: SWE-ReX is asynchronous; use asyncio to manage the event loop.

    import asyncio
from swerex.deployment.local import LocalDeployment
from swerex.runtime.abstract import CreateBashSessionRequest, BashAction, Command

deployment = LocalDeployment()

async def run_some_stuff(deployment):
    await deployment.start()
    runtime = deployment.runtime

    # One-off command
    print(await runtime.execute(Command(command=["echo", "Hello, world!"])))

    # Persistent session
    await runtime.create_session(CreateBashSessionRequest())
    print(await runtime.run_in_session(BashAction(command="export MYVAR='test'")))
    print(await runtime.run_in_session(BashAction(command="echo $MYVAR")))

    await deployment.stop()

asyncio.run(run_some_stuff(deployment))

  10. Run commands in a sandbox with DockerDeployment

    main

    Switch to DockerDeployment to run commands inside a sandboxed Docker container. This allows you to specify a base image and ensures your host machine remains untouched.

    Workflow:

    1. Instantiate DockerDeployment(image="<image_name>").
    2. Pass the deployment instance to your existing logic (the API is compatible with LocalDeployment).
    3. SWE-ReX will pull the image, start a container, and run swerex-remote inside it to handle command execution.

    Example usage:

    from swerex.deployment.docker import DockerDeployment
import asyncio

deployment = DockerDeployment(image="python:3.12")
# Use the same logic as LocalDeployment
asyncio.run(run_some_stuff(deployment))
    from swerex.deployment.docker import DockerDeployment
import asyncio

deployment = DockerDeployment(image="python:3.12")
asyncio.run(run_some_stuff(deployment))

  11. Install the latest development version

    main

    To install the latest development version from the source repository, clone the repository and install it in editable mode with development dependencies.

    git clone https://github.com/SWE-agent/swe-rex
cd swe-rex
pip install -e '.[dev]'

  12. Configure MkDocs to support the navigation footer

    main

    To ensure the footer's styling and icons load correctly, your mkdocs.yml configuration must include the Material Icons font and the custom CSS file.

    Ensure your mkdocs.yml contains:

    1. The Material Icons font from Google Fonts.
    2. docs/css/navigation_cards.css added to the extra_css list.