Skip to content

File Storage & Sandbox Backends for Pydantic AI

Console Toolset, Docker Sandbox, and Permission System for Pydantic AI agents.

pydantic-ai-backend provides file storage, sandbox execution, and a ready-to-use console toolset for pydantic-ai agents. Give your AI agents the ability to read, write, and execute code safely.

  • Console Toolset

    Ready-to-use tools: ls, read, write, edit, glob, grep, execute

  • Docker Isolation

    Execute code safely in isolated containers

  • Multiple Backends

    In-memory, filesystem, Docker — same interface

  • Permission System

    Fine-grained access control with presets

Quick Start (Capability API)

The recommended way to add filesystem tools:

Python
from pydantic_ai import Agent
from pydantic_ai_backends import ConsoleCapability

agent = Agent("openai:gpt-4.1", capabilities=[ConsoleCapability()])

With Permissions

Python
from pydantic_ai_backends import ConsoleCapability
from pydantic_ai_backends.permissions import READONLY_RULESET

# Read-only agent — write/edit/execute tools hidden from model
agent = Agent("openai:gpt-4.1", capabilities=[
    ConsoleCapability(permissions=READONLY_RULESET),
])

Alternative: Toolset API

Python
from dataclasses import dataclass
from pydantic_ai import Agent
from pydantic_ai_backends import LocalBackend, create_console_toolset

@dataclass
class Deps:
    backend: LocalBackend

agent = Agent("openai:gpt-4.1", deps_type=Deps, toolsets=[create_console_toolset()])

Choose Your Backend

Same toolset, different backends — swap based on your use case:

Python
from pydantic_ai_backends import LocalBackend

backend = LocalBackend(root_dir="./workspace")
Python
from pydantic_ai_backends import StateBackend

backend = StateBackend()  # In-memory, no side effects
Python
from pydantic_ai_backends import DockerSandbox

backend = DockerSandbox(runtime="python-datascience")
Python
from pydantic_ai_backends import SessionManager

manager = SessionManager(workspace_root="/app/workspaces")
backend = await manager.get_or_create(user_id="alice")

Available Tools

Tool Description
ls List files in a directory
read_file Read file content with line numbers
write_file Create or overwrite a file
edit_file Replace strings in a file
glob Find files matching a pattern
grep Search for patterns in files
execute Run shell commands (optional)

Backend Comparison

Backend Persistence Execution Best For
LocalBackend Persistent Yes CLI tools, local dev
StateBackend Ephemeral No Testing, mocking
DockerSandbox Ephemeral* Yes Safe execution, multi-user
CompositeBackend Mixed Depends Route by path prefix

*DockerSandbox supports persistent volumes via workspace_root parameter.

Package Description
Pydantic Deep Agents Full agent framework (uses this library)
pydantic-ai-todo Task planning toolset
subagents-pydantic-ai Multi-agent orchestration
summarization-pydantic-ai Context management
pydantic-ai The foundation — agent framework by Pydantic

Next Steps