Virtual Filesystem

Features

• Persistent file storage — files are stored in PostgreSQL and survive process restarts, container recycling, and redeployments
• Session isolation — each agent session gets its own namespace automatically, no configuration needed
• Cross-session stores — named persistent stores for sharing data between agents or for long-term agent memory
• 11 POSIX-style tools — read, write, append, stat, ls, mkdir, rm, mv, glob, grep, stores
• Glob and grep search — find files by pattern or search content by regex, powered by PostgreSQL trigram indexes
• Row Level Security — optional database-enforced isolation between sessions for multi-tenant deployments
• Zero config — auto-creates tables on first run with VFS_AUTO_INIT=true

Use Cases

• Agent scratchpad — persistent workspace to read/write files across tool calls
• Long-term agent memory — store notes, context, and knowledge across sessions
• Multi-agent collaboration — multiple agents share files through cross-session stores
• Sandboxed file operations — agents interact with a virtual filesystem instead of the host OS

Quick Start

1. Run PostgreSQL (e.g. docker run -d -e POSTGRES_DB=vfs -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16-alpine)
2. Add the server config to your MCP client
3. Start using tools: write, read, ls, glob, grep, etc.

Environment Variables

| Variable | Required | Description | |--------|--------| | DATABASE_URL | Yes | PostgreSQL connection string | | VFS_AUTO_INIT | No | Auto-create tables on startup | | VFS_SESSION_ID | No | Deterministic session ID for resumable sessions | | VFS_ENABLE_RLS | No | Enable Row Level Security |