{"id":35135353,"url":"https://github.com/vstorm-co/pydantic-ai-backend","last_synced_at":"2026-02-25T23:17:53.419Z","repository":{"id":330799386,"uuid":"1123991249","full_name":"vstorm-co/pydantic-ai-backend","owner":"vstorm-co","description":"File Storage \u0026 Sandbox Backends for Pydantic AI: console tools for file operations, Docker-isolated sandboxes for safe execution, and permission system with presets for access control. Enables secure multi-user handling and testing in agents via in-memory, local, or containerized storage.","archived":false,"fork":false,"pushed_at":"2026-02-24T09:06:48.000Z","size":7904,"stargazers_count":36,"open_issues_count":0,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-24T15:15:55.121Z","etag":null,"topics":["ai-agent-framework","aiagentframework","anthropic","backend","chatgpt","docker","framework","gemini","llms","mcp","multiagent","openai","pydantic","pydantic-ai","python","sandbox"],"latest_commit_sha":null,"homepage":"https://vstorm-co.github.io/pydantic-ai-backend/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vstorm-co.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-28T04:42:20.000Z","updated_at":"2026-02-24T09:06:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vstorm-co/pydantic-ai-backend","commit_stats":null,"previous_names":["vstorm-co/pydantic-ai-backend"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/vstorm-co/pydantic-ai-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fpydantic-ai-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fpydantic-ai-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fpydantic-ai-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fpydantic-ai-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vstorm-co","download_url":"https://codeload.github.com/vstorm-co/pydantic-ai-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fpydantic-ai-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29844849,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T22:37:40.667Z","status":"ssl_error","status_checked_at":"2026-02-25T22:37:25.960Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent-framework","aiagentframework","anthropic","backend","chatgpt","docker","framework","gemini","llms","mcp","multiagent","openai","pydantic","pydantic-ai","python","sandbox"],"created_at":"2025-12-28T08:54:04.673Z","updated_at":"2026-02-25T23:17:53.387Z","avatar_url":"https://github.com/vstorm-co.png","language":"Python","funding_links":[],"categories":["Frameworks \u0026 Libraries","Python"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eFile Storage \u0026 Sandbox Backends for Pydantic AI\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eConsole Toolset, Docker Sandbox, and Permission System for AI Agents\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/pydantic-ai-backend/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/pydantic-ai-backend.svg\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.10+-blue.svg\" alt=\"Python 3.10+\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/vstorm-co/pydantic-ai-backend/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/vstorm-co/pydantic-ai-backend/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/pydantic/pydantic-ai\"\u003e\u003cimg src=\"https://img.shields.io/badge/Powered%20by-Pydantic%20AI-E92063?logo=pydantic\u0026logoColor=white\" alt=\"Pydantic AI\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eConsole Toolset\u003c/b\u003e — ls, read, write, edit, grep, execute\n  \u0026nbsp;\u0026bull;\u0026nbsp;\n  \u003cb\u003eDocker Sandbox\u003c/b\u003e — isolated code execution\n  \u0026nbsp;\u0026bull;\u0026nbsp;\n  \u003cb\u003ePermission System\u003c/b\u003e — fine-grained access control\n\u003c/p\u003e\n\n---\n\n**File Storage \u0026 Sandbox Backends** provides everything your [Pydantic AI](https://ai.pydantic.dev/) agent needs to work with files and execute code safely. Choose from in-memory, local filesystem, or Docker-isolated backends.\n\n\u003e **Full framework?** Check out [Pydantic Deep Agents](https://github.com/vstorm-co/pydantic-deepagents) — complete agent framework with planning, filesystem, subagents, and skills.\n\n## Use Cases\n\n| What You Want to Build | How This Library Helps |\n|------------------------|------------------------|\n| **AI Coding Assistant** | Console toolset with file ops + code execution |\n| **Multi-User Web App** | Docker sandboxes with session isolation |\n| **Code Review Bot** | Read-only backend with grep/glob search |\n| **Secure Execution** | Permission system blocks dangerous operations |\n| **Testing/CI** | In-memory StateBackend for fast, isolated tests |\n\n## Installation\n\n```bash\npip install pydantic-ai-backend\n```\n\nOr with uv:\n\n```bash\nuv add pydantic-ai-backend\n```\n\nOptional extras:\n\n```bash\n# Console toolset (requires pydantic-ai)\npip install pydantic-ai-backend[console]\n\n# Docker sandbox support\npip install pydantic-ai-backend[docker]\n\n# Everything\npip install pydantic-ai-backend[console,docker]\n```\n\n## Quick Start\n\n```python\nfrom dataclasses import dataclass\nfrom pydantic_ai import Agent\nfrom pydantic_ai_backends import LocalBackend, create_console_toolset\n\n@dataclass\nclass Deps:\n    backend: LocalBackend\n\nagent = Agent(\n    \"openai:gpt-4o\",\n    deps_type=Deps,\n    toolsets=[create_console_toolset()],\n)\n\nbackend = LocalBackend(root_dir=\"./workspace\")\nresult = agent.run_sync(\n    \"Create a Python script that calculates fibonacci and run it\",\n    deps=Deps(backend=backend),\n)\nprint(result.output)\n```\n\n**That's it.** Your agent can now:\n\n- List files and directories (`ls`)\n- Read and write files (`read_file`, `write_file`)\n- Edit files with string replacement (`edit_file`)\n- Search with glob patterns and regex (`glob`, `grep`)\n- Execute shell commands (`execute`)\n\n## Available Backends\n\n| Backend | Storage | Execution | Use Case |\n|---------|---------|-----------|----------|\n| `StateBackend` | In-memory | No | Testing, ephemeral sessions |\n| `LocalBackend` | Filesystem | Yes | Local development, CLI tools |\n| `DockerSandbox` | Container | Yes | Multi-user, untrusted code |\n| `CompositeBackend` | Routed | Varies | Complex multi-source setups |\n\n### In-Memory (StateBackend)\n\n```python\nfrom pydantic_ai_backends import StateBackend\n\nbackend = StateBackend()\n# Files stored in memory, perfect for tests\n```\n\n### Local Filesystem (LocalBackend)\n\n```python\nfrom pydantic_ai_backends import LocalBackend\n\nbackend = LocalBackend(\n    root_dir=\"/workspace\",\n    allowed_directories=[\"/workspace\", \"/shared\"],\n    enable_execute=True,\n)\n```\n\n### Docker Sandbox (DockerSandbox)\n\n```python\nfrom pydantic_ai_backends import DockerSandbox\n\nsandbox = DockerSandbox(runtime=\"python-datascience\")\nsandbox.start()\n# Fully isolated container environment\nsandbox.stop()\n```\n\n## Console Toolset\n\nReady-to-use tools for pydantic-ai agents:\n\n```python\nfrom pydantic_ai_backends import create_console_toolset\n\n# All tools enabled\ntoolset = create_console_toolset()\n\n# Without shell execution\ntoolset = create_console_toolset(include_execute=False)\n\n# With approval requirements\ntoolset = create_console_toolset(\n    require_write_approval=True,\n    require_execute_approval=True,\n)\n```\n\n**Available tools:** `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `execute`\n\n### Image Support\n\nFor multimodal models, enable image file handling:\n\n```python\ntoolset = create_console_toolset(image_support=True)\n\n# Now read_file on .png/.jpg/.gif/.webp returns BinaryContent\n# that multimodal models (GPT-4o, Claude, etc.) can see directly\n```\n\n## Permission System\n\nFine-grained access control:\n\n```python\nfrom pydantic_ai_backends import LocalBackend\nfrom pydantic_ai_backends.permissions import DEFAULT_RULESET, READONLY_RULESET\n\n# Safe defaults (allow reads, ask for writes)\nbackend = LocalBackend(root_dir=\"/workspace\", permissions=DEFAULT_RULESET)\n\n# Read-only mode\nbackend = LocalBackend(root_dir=\"/workspace\", permissions=READONLY_RULESET)\n```\n\n| Preset | Description |\n|--------|-------------|\n| `DEFAULT_RULESET` | Allow reads (except secrets), ask for writes/executes |\n| `PERMISSIVE_RULESET` | Allow most operations, deny dangerous commands |\n| `READONLY_RULESET` | Allow reads only, deny all writes and executes |\n| `STRICT_RULESET` | Everything requires approval |\n\n## Docker Runtimes\n\nPre-configured environments:\n\n| Runtime | Base Image | Packages |\n|---------|------------|----------|\n| `python-minimal` | python:3.12-slim | (none) |\n| `python-datascience` | python:3.12-slim | pandas, numpy, matplotlib, scikit-learn |\n| `python-web` | python:3.12-slim | fastapi, uvicorn, sqlalchemy, httpx |\n| `node-minimal` | node:20-slim | (none) |\n| `node-react` | node:20-slim | typescript, vite, react |\n\nCustom runtime:\n\n```python\nfrom pydantic_ai_backends import DockerSandbox, RuntimeConfig\n\nruntime = RuntimeConfig(\n    name=\"ml-env\",\n    base_image=\"python:3.12-slim\",\n    packages=[\"torch\", \"transformers\"],\n)\nsandbox = DockerSandbox(runtime=runtime)\n```\n\n## Session Manager\n\nMulti-user web applications:\n\n```python\nfrom pydantic_ai_backends import SessionManager\n\nmanager = SessionManager(\n    default_runtime=\"python-datascience\",\n    workspace_root=\"/app/workspaces\",\n)\n\n# Each user gets isolated sandbox\nsandbox = await manager.get_or_create(\"user-123\")\n```\n\n## Why Choose This Library?\n\n| Feature | Description |\n|---------|-------------|\n| **Multiple Backends** | In-memory, filesystem, Docker — same interface |\n| **Console Toolset** | Ready-to-use tools for pydantic-ai agents |\n| **Permission System** | Pattern-based access control with presets |\n| **Docker Isolation** | Safe execution of untrusted code |\n| **Session Management** | Multi-user support with workspace persistence |\n| **Image Support** | Multimodal models can see images via BinaryContent |\n| **Pre-built Runtimes** | Python and Node.js environments ready to go |\n\n## Related Projects\n\n| Package | Description |\n|---------|-------------|\n| [Pydantic Deep Agents](https://github.com/vstorm-co/pydantic-deepagents) | Full agent framework (uses this library) |\n| [pydantic-ai-todo](https://github.com/vstorm-co/pydantic-ai-todo) | Task planning toolset |\n| [subagents-pydantic-ai](https://github.com/vstorm-co/subagents-pydantic-ai) | Multi-agent orchestration |\n| [summarization-pydantic-ai](https://github.com/vstorm-co/summarization-pydantic-ai) | Context management |\n| [pydantic-ai](https://github.com/pydantic/pydantic-ai) | The foundation — agent framework by Pydantic |\n\n## Contributing\n\n```bash\ngit clone https://github.com/vstorm-co/pydantic-ai-backend.git\ncd pydantic-ai-backend\nmake install\nmake test  # 100% coverage required\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt with ❤️ by \u003ca href=\"https://github.com/vstorm-co\"\u003evstorm-co\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvstorm-co%2Fpydantic-ai-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvstorm-co%2Fpydantic-ai-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvstorm-co%2Fpydantic-ai-backend/lists"}