**Project:** [Mirage](https://github.com/strukto-ai/mirage) by [strukto-ai](https://github.com/strukto-ai) | ⭐ 1,970 | TypeScript | [github.com/strukto-ai/mirage](https://github.com/strukto-ai/mirage)

---

## Project Introduction

Mirage is a unified virtual filesystem (VFS) purpose-built for AI agents, developed by Strukto AI. Instead of tying agents to a single storage backend, Mirage lets you mount in-memory workspaces, Redis stores, S3 buckets, and FUSE filesystems through a single consistent shell command interface. Agents can `cat`, `grep`, `ls`, and `find` across heterogeneous backends using the exact same syntax — no backend-specific SDK knowledge required. It's a thin, elegant abstraction layer that makes multi-backend corpus access composable and shell-scriptable, with clients for TypeScript, Python, and Rust.

## Key Features

- **Backend-agnostic shell interface.** Workspace commands (`cat`, `ls`, `grep`, `find`) work identically whether the backing store is RAM, Redis, S3, or FUSE. Agents write once, access anywhere — dramatically reducing the backend-specific boilerplate in agentic pipelines.
- **Multi-client support.** Officially supported clients for TypeScript (`@struktoai/mirage-node`), Python (`mirage-py`), and Rust (`mirage-rs`) — making it easy to integrate into any agent harness regardless of language.
- **AI-native storage integration.** The project has already attracted interest from Hugging Face (Issue #1) to explore HF Buckets as a backend, and from Convex (Issue #2) for database integration — signaling real traction in the AI tooling ecosystem.
- **Extensible backend architecture.** The codebase is designed for new backends to plug in via a consistent interface. Batch operations, concurrent reads, and streaming are all backend-aware, not baked into a single implementation.

## Community Discussions

**Issue #6 — Bug: `AbortSignal` only checked at entry, never observed mid-execution** *(1 comment — resolved)*

> *Reporter documents:* "`Workspace.execute(command, { signal })` documents an AbortSignal option, but the signal is only checked once at the very start of the call. Aborts that fire mid-flight are silently ignored — long-running commands run to completion regardless."

The Mirage team confirmed this was a real bug and resolved it in PR #7. `AbortSignal` (TypeScript) and `asyncio.Event` (Python `cancel=`) are now observed at all recursion boundaries: LIST, PIPELINE, FOR/WHILE/UNTIL, COMMAND, subshells, command substitution, and inside `sleep`. This fix is critical for agent harnesses that need hard timeouts — without it, runaway commands would consume resources indefinitely.

**Issue #3 — Multi-file shell ops perform per-file sequential reads — opportunity for backend-aware batching** *(1 comment — open)*

> *Evaluator notes:* "We noticed that multi-file shell ops loop per-file rather than expressing a batch. `cat file1 file2 ...` calls per-file `get_file()`, and grep performs recursive entry walk + per-file reads. Both Redis (MGET/pipelined GET) and S3 (concurrent GetObject via asyncio.gather) have natural batched primitives the current pattern can't express."

This is a thoughtful performance-oriented issue from a team evaluating Mirage for production use over Redis and S3 backends. The maintainer responded positively ("Will take a look soon!"), suggesting batch operations are on the roadmap.

**Issue #5 — Feature: support per-call `env` in `ExecuteOptions`** *(1 comment — open)*

> *Requester explains:* "Workspace.execute currently has no way to inject per-call environment variables. Mutating session.env then restoring is racy if two execute() calls overlap, and shell command-prefix `FOO=bar cmd` silently produces wrong results today."

Agents frequently need per-call scoped env vars — feature flags, scoped credentials, request-scoped tokens. Without a first-class `env` option, every caller has to reinvent snapshot/restore logic. This is a high-impact ergonomic improvement for the agent harness ecosystem.

## Summary

Mirage fills a real gap in the AI agent tooling landscape: instead of hard-coding storage backends into agent pipelines, it provides a clean VFS abstraction that makes any storage backend look like a filesystem. With multi-language client support, active community engagement, and growing interest from major platforms (Hugging Face, Convex), it's quickly becoming the go-to solution for agents that need to work across heterogeneous data sources. Worth exploring if you're building agent harnesses today.

---

*@strukto-ai · [Mirage on GitHub](https://github.com/strukto-ai/mirage)*