How Strukto.ai built Mirage’s Pydantic AI integration on Vstorm’s pydantic-ai-backend

This article documents how Mirage, the open-source virtual filesystem for AI agents from Strukto.ai, built its Pydantic AI integration on Vstorm’s pydantic-ai-backend, verified directly in Mirage’s source code.

The TL;DR: Mirage, Strukto.ai’s open-source unified virtual filesystem for AI agents, builds its Pydantic AI integration on pydantic-ai-backend, an MIT-licensed library produced and maintained by our work at Vstorm. Mirage implements the library’s SandboxProtocol and uses its console toolset, so a Pydantic AI agent can read, write, grep, and execute across backends like Amazon S3, Slack, and GitHub through one standard interface.

• What Vstorm’s pydantic-ai-backend is: file storage and sandbox backends, a seven-tool console toolset, and a permission system for Pydantic AI agents (MIT-licensed, latest release 0.2.4).
• How Mirage uses it: a version-pinned dependency in Mirage’s pydantic-ai extra; Mirage’s PydanticAIWorkspace class implements our Vstorm SandboxProtocol; Strukto’s own examples and integration tests build agents with create_console_toolset().
• Why it matters: Strukto reused our Vstorm designed abstraction for a backend its authors never anticipated: an entire virtual filesystem spanning remote services.

When you open-source a library, the most meaningful validation is not a star count, but another team making it a hard dependency in production code. That is how our pydantic-ai-backend was used: Strukto.ai, a team with roots at AWS AI, Stanford, and Y Combinator, built their Pydantic AI integration for Mirage on top of it. The proof of this is not just a logo on our landing page, it can be found in Strukto’s source tree, which we reference directly in this article.

What Mirage is and the problem it solves

Mirage is an open-source (Apache-2.0) unified virtual filesystem for AI agents, first released publicly as v0.0.1 on May 6, 2026. The idea is deceptively simple: mount every backend an agent might touch (Amazon S3, Google Drive, GitHub, Slack, Gmail, Postgres, Redis, and roughly a dozen more), side by side under a single root, and let the agent operate on all of them with the same handful of Unix-like tools.

Instead of teaching an agent a different SDK for each service, Mirage lets it stay in the one vocabulary modern LLMs are most fluent in: the filesystem and bash. A single command can read a Parquet file out of S3, grep a Slack export, and write the result into memory, pipes and all. Around that core, Mirage adds a two-layer cache so repeated reads collapse into local lookups, git-style snapshots and clones, and workspace portability as a single .tar. It ships Python and TypeScript SDKs plus a CLI, and supports seven agent frameworks.

Strukto’s framing is that LLMs reason better about one abstraction than about “N SDKs and M MCPs.” But that framing raises an immediate engineering question. If the agent acts through file and shell operations, something has to define the contract for those operations inside whatever agent framework you are using, and then route each call to the real backend. For the Pydantic AI ecosystem, that contract is exactly what our pydantic-ai-backend provides.

What Vstorm’s pydantic-ai-backend is and where it fits

pydantic-ai-backend is our Vstorm designed and MIT-licensed library of file storage and sandbox backends for Pydantic AI. In agent terms, a “backend” is where the agent’s file reads, writes, and code execution actually happen: the layer that decides whether write_file lands in memory, on local disk, or inside an isolated container. Our pydantic-ai-backend gives an agent three things out of the box:

• A console toolset of seven operations (ls, read_file, write_file, edit_file, glob, grep, and execute) ready to hand to a Pydantic AI agent.
• Four interchangeable backends behind one interface: StateBackend (in-memory), LocalBackend (filesystem), DockerSandbox (isolated container, with five preconfigured runtimes), and CompositeBackend (routed).
• A permission system with four presets (read-only, default, permissive, and strict) so write and execute operations can be gated per agent.

The piece that matters most for the Mirage story is the abstraction underneath all of that: Vstorm’s SandboxProtocol. It defines what a “place where the agent does file and shell work” must be able to do: execute a command, list a directory, read, write, edit, grep, and glob. Because the toolset talks to that protocol rather than to any concrete storage, anything that implements SandboxProtocol instantly works with a Pydantic AI agent. We at Vstorm built the protocol to swap in-memory state, local disk, and Docker. But Strukto used it to swap in something we never anticipated: an entire virtual filesystem spanning remote services.

How Mirage uses Vstorm’s pydantic-ai-backend

These findings come from a direct audit of Mirage’s repository (the Python package metadata, the lockfile, the Pydantic AI adapter, the examples, and the tests). Three things stand out:

1. It is a declared, version-pinned dependency. Mirage’s Python pyproject.toml lists pydantic-ai-backend>=0.1.0 under its pydantic-ai extra (alongside pydantic-ai-slim), and Mirage’s lockfile pins it to release 0.2.4. This is not an optional mention: installing Mirage’s Pydantic AI support pulls in Vstorm’s library.

2. Mirage implements Vstorm’s protocol. In mirage/agents/pydantic_ai/backend.py, Strukto defines a class that subclasses Vstorm’s SandboxProtocol and reuses its type system directly:

from pydantic_ai_backends.protocol import SandboxProtocol
from pydantic_ai_backends.types import (
    EditResult, ExecuteResponse, FileInfo, GrepMatch, WriteResult,
)

class PydanticAIWorkspace(SandboxProtocol):
    """Pydantic AI backend backed by a Mirage Workspace."""
    ...

Each method of the protocol is wired to Mirage’s own machinery: execute and grep route through Workspace.execute() to get real pipe and flag support across mounts, while read, write, and edit go through Mirage’s ops layer. The results come back as our Vstorm types: ExecuteResponse, FileInfo, GrepMatch, EditResult, and WriteResult. In other words, our SandboxProtocol is the seam that lets Mirage’s filesystem present itself to a Pydantic AI agent as a perfectly ordinary sandbox.

3. Strukto’s examples and tests use Vstorm’s toolset. Strukto’s own example agents and their integration tests build the agent with create_console_toolset() from pydantic-ai-backend:

from pydantic_ai import Agent
from pydantic_ai_backends import create_console_toolset

from mirage import MountMode, Workspace
from mirage.agents.pydantic_ai import PydanticAIWorkspace, build_system_prompt
from mirage.resource.s3 import S3Config, S3Resource

ws = Workspace({"/s3/": S3Resource(config)}, mode=MountMode.READ)
backend = PydanticAIWorkspace(ws)

agent = Agent(
    "openai:gpt-4.1",
    system_prompt=build_system_prompt(mount_info={"/s3/": "S3 bucket"}),
    deps_type=Deps,
    toolsets=[create_console_toolset()],
)

result = agent.run_sync("Explore and summarize the data in /s3/data/.", deps=Deps(backend=backend))

Read that flow end to end: an S3 bucket is mounted as a Mirage workspace, wrapped in a PydanticAIWorkspace that satisfies our SandboxProtocol, and handed to a Pydantic AI agent armed with create_console_toolset(). The agent thinks it’s running ordinary console tools. Underneath, every read and grep is served by Mirage across a remote backend.

One honest note on scope: this dependency is specific to Mirage’s Pydantic AI integration. Mirage also ships adapters for OpenAI Agents SDK, Vercel AI SDK, LangChain, CAMEL, Mastra, and OpenHands, which do not use Vstorm’s library. The point is worth stating plainly, because the precise version of the claim is the stronger one: Strukto chose our protocol as the standard interface for the Pydantic AI path specifically.

Key takeaways

• pydantic-ai-backend is a hard, version-pinned dependency of Mirage’s Pydantic AI integration (0.2.4 in Mirage’s lockfile).
• Mirage’s PydanticAIWorkspace subclasses Vstorm’s SandboxProtocol and reuses its types: ExecuteResponse, FileInfo, GrepMatch, EditResult, and WriteResult.
• Strukto’s own example agents and integration tests call create_console_toolset() from pydantic-ai-backend.
• The dependency is scoped to the Pydantic AI path; Mirage’s other framework adapters don’t use it.

Why a well-designed contract gets reused

The reason this adoption is satisfying is not that someone used our code. It is which part they used and how. Strukto did not fork the backends or copy a helper function. They built against the abstraction, our SandboxProtocol contract and its type system, and supplied their own implementation behind it.

That is the clearest possible signal that an interface was designed well: it gets reused for a backend we never had in mind. We designed pydantic-ai-backend so a Pydantic AI agent could move between in-memory state, local disk, and a Docker sandbox without changing a line of agent code. Strukto extended that same idea so the agent can now also operate over a unified filesystem spanning S3, Slack, GitHub, and the rest, and to the agent, nothing about the surface changed.

That is the whole promise of a good contract: the agent reasons about one stable interface, and the hard, service-specific work happens out of sight, on the other side of the protocol.

Part of a larger toolkit

Our Vstorm maintained pydantic-ai-backend is one piece of a set of composable building blocks for the Pydantic AI ecosystem, including Pydantic Deep Agents (a full agent framework that builds on this library), pydantic-ai-todo for task planning, subagents-pydantic-ai for multi-agent orchestration, and summarization-pydantic-ai for context management. The Mirage integration is concrete proof that these pieces hold up when a team outside Vstorm leans on them in earnest.

Try it yourself

Vstorm’s pydantic-ai-backend is open source under the MIT license:

pip install pydantic-ai-backend

The repository, docs, and examples live at github.com/vstorm-co/pydantic-ai-backend. To see the integration discussed here in context, Mirage is open source too, at github.com/strukto-ai/mirage.