How to use the GuardiAgent Framework

Attack on Titan

Quick Start

To use the GuardiAgent Security Sandbox, use the following quick start steps. GuardiAgent is not dependent on a specific AI framework, it works with all SDKs. However, this quickstart shows how to use GuardiAgent with the OpenAI Agent SDK. Currently, we support the OpenAI Agent SDK out of the box with an SDK specific implementation.

uv init
uv add openai-agents
uv add https://github.com/GuardiAgent/python-mcp-sandbox-openai-sdk.git

import os

from agents import Agent, Runner

from mcp_sandbox_openai_sdk import (
    FSAccess,
    MCPManifest,
    MCPServers,
    Permission,
    Registry,
    SandboxedMCPStdio,
)

manifest = MCPManifest( 
    name="Filesystem Server",
    description="A server that access the local filesystem and allows interaction with all sorts of files.",
    registry=Registry.NPM,
    package_name="@modelcontextprotocol/server-filesystem",
    permissions=[
        Permission.MCP_AC_FILESYSTEM_READ,
        Permission.MCP_AC_FILESYSTEM_WRITE,
        Permission.MCP_AC_FILESYSTEM_DELETE,
    ],
)


async def main():
    async with MCPServers(
        SandboxedMCPStdio( 
            manifest=manifest,
            runtime_args=[os.path.abspath("./")],
            runtime_permissions=[FSAccess(os.path.abspath("./"))],
        )
    ) as servers:
        agent = Agent(
            name="MCP Sandbox Test",
            model="gpt-5-mini",
            mcp_servers=servers,
        )

        prompt = f"""
            Read the files in the {os.path.abspath("./")} directory and
            list all the found files and directories of the first level.
            Do not decend recursively.
            Use the provided mcp servers to access the filesystem.
        """
        result = await Runner.run(
            agent,
            input=prompt,
        )
        print(result.final_output)


if __name__ == "__main__":
    import asyncio

    print("Execute Sandbox Demo")
    asyncio.run(main())

Runtime Permission: File System Access Permission
Allow access to file system path: .../example (read: True, write: False)
Do you want to give the agent the requested access? (yes/no):

The Security Manifest

One key ingredient of the GuardiAgent framework is the security manifest (in our research, we call it the policy). It is a JSON file, that is bundled together with the MCP server that defines what general intentions an MCP server may have. This defines overarching intentions like file-access or internet access. It is inspired by the Android Permissions Manifest for apps.

{
  "name": "Filesystem Server",
  "description": "A server that access the local filesystem and allows interaction with all sorts of files.",
  "registry": "npm",
  "package_name": "@modelcontextprotocol/server-filesystem",
  "permissions": [ 
    "mcp.ac.filesystem.read",
    "mcp.ac.filesystem.write",
    "mcp.ac.filesystem.delete"
  ]
}

SandboxedMCPStdio(
    manifest=manifest,
    runtime_args=[os.path.abspath("./")],
    runtime_permissions=[FSAccess(os.path.abspath("./"))],
)

Runtime Permissions

Sandboxed Container Images

The sandbox currently works with Docker underneath. There is a base image that you can use to create your own customized runtime image. The custom entrypoint performs the following tasks:

1. Check setup variables
2. Download and setup the server package
3. Check hostnames and setup iptables
4. Execute the MCP server

The following configuration environment variables are available during setup:

• PRE_INSTALLED: Skip package installation and use a pre-installed/mounted MCP server. Requires EXE to be set.
• RUNTIME: Specifies the package manager runtime, either "pypi" for Python packages or "npm" for Node.js packages.
• PACKAGE: The name of the MCP server package to install from the specified registry (npm or PyPI).
• EXE: The command to execute the MCP server. Required when PRE_INSTALLED is set, otherwise auto-configured.
• ALLOWED_EGRESS: Space or comma-separated list of allowed outbound connections in "host:port" or "ip:port" format. Empty by default (no outbound access).
• EXTRA_DNS: Additional DNS servers to allow for resolution beyond those in /etc/resolv.conf.
• ALLOW_LOOPBACK: Enable loopback traffic (localhost). Defaults to "1" (enabled). Set to "0" to disable.

Note that after the download of the server package from the official package repository, only outbound connections allowed by DOMAIN/PORT or IP/PORT are possible. IPTABLES will block everything else.