{"id":24310,"library":"pydantic-ai-backend","title":"Pydantic AI Backend","description":"File storage and sandbox backends for AI agents built with pydantic-ai. Provides backends (LocalBackend, DockerSandbox, DaytonaSandbox) and console tools (ls, read, write, glob, grep, execute) bundled as pydantic-ai capabilities. Current version 0.2.5. Release cadence: weekly.","status":"active","version":"0.2.5","language":"python","source_language":"en","source_url":"https://github.com/vstorm-co/pydantic-ai-backend","tags":["pydantic-ai","backend","sandbox","file-storage","ai-agents","docker","daytona"],"install":[{"cmd":"pip install pydantic-ai-backend","lang":"bash","label":"Core install"},{"cmd":"pip install pydantic-ai-backend[daytona]","lang":"bash","label":"With Daytona support"}],"dependencies":[{"reason":"Core dependency for capabilities and toolsets","package":"pydantic-ai-slim","optional":false},{"reason":"Cloud sandbox backend (DaytonaSandbox)","package":"daytona-sdk","optional":true},{"reason":"Docker sandbox backend (DockerSandbox)","package":"docker","optional":true}],"imports":[{"note":"Package name uses plural 'backends'","wrong":"from pydantic_ai_backend import LocalBackend","symbol":"LocalBackend","correct":"from pydantic_ai_backends import LocalBackend"},{"note":"Top-level import, not nested","wrong":"from pydantic_ai_backends.sandbox import DockerSandbox","symbol":"DockerSandbox","correct":"from pydantic_ai_backends import DockerSandbox"},{"symbol":"ConsoleCapability","correct":"from pydantic_ai_backends import ConsoleCapability"},{"symbol":"READONLY_RULESET","correct":"from pydantic_ai_backends.permissions import READONLY_RULESET"},{"note":"Not in a protocol module","wrong":"from pydantic_ai_backends.protocol import SandboxProtocol","symbol":"SandboxProtocol","correct":"from pydantic_ai_backends import SandboxProtocol"}],"quickstart":{"code":"from pydantic_ai import Agent\nfrom pydantic_ai_backends import LocalBackend, ConsoleCapability\nfrom pydantic_ai_backends.permissions import READONLY_RULESET\n\nagent = Agent(\n    \"openai:gpt-4.1\",\n    capabilities=[ConsoleCapability(permissions=READONLY_RULESET)],\n    system_prompt=\"You can read files in the current directory.\",\n)\nbackend = LocalBackend(work_dir=\"/tmp/demo\")\nwith backend as b:\n    b.write(\"hello.txt\", b\"Hello, world!\")\n    result = agent.run_sync(\"Read hello.txt\", deps=b)\n    print(result.data)","lang":"python","description":"Create an agent with console capability, using LocalBackend to read/write files."},"warnings":[{"fix":"Use 'from pydantic_ai_backends import ...' instead of 'from pydantic_ai_backend import ...'","message":"Imports changed from 'pydantic_ai_backend' (singular) to 'pydantic_ai_backends' (plural) after v0.1.x.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Upgrade to >=0.2.5 for correct recursive glob support.","message":"Globstar patterns (e.g., '**/*.md') in glob_info and glob tools did not match nested files before v0.2.5. Only now fixed to use find -path.","severity":"gotcha","affected_versions":"<0.2.5"},{"fix":"Wrap backend calls in asyncio.to_thread() if called from async context.","message":"BackendProtocol methods are synchronous. When using them inside async agent tools (e.g., ConsoleCapability), ensure calls are wrapped in asyncio.to_thread() to avoid blocking the event loop. The built-in toolset from >=0.2.3 already wraps them; custom tools must handle this.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Upgrade: pip install --upgrade pydantic-ai-backend","cause":"Installed old version (<0.2.0) where package was named 'pydantic_ai_backend' (singular).","error":"ModuleNotFoundError: No module named 'pydantic_ai_backends'"},{"fix":"Install with docker extra: pip install pydantic-ai-backend[docker] and ensure version >=0.1.12","cause":"Missing docker extra or old version before DockerSandbox was added (v0.1.12).","error":"AttributeError: module 'pydantic_ai_backends' has no attribute 'DockerSandbox'"},{"fix":"Use: from pydantic_ai_backends.permissions import READONLY_RULESET","cause":"Import path changed after v0.2.0; previously might have been in a different location.","error":"pydantic_ai_backends.permissions.READONLY_RULESET"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}