Skip to main content
RedisVFS keeps a filesystem in Redis: every file is one key under keyPrefix, and the tree is whatever commands write. Files persist across processes, and every workspace pointed at the same URL and prefix sees them. Set up the server as in Redis setup.

Install

Configure

Node speaks the Redis protocol over a socket and needs the redis@^5 peer package. capacity: '100MB' caps the bytes the files hold; see capacity. A mount takes MountMode.READ, WRITE or EXEC.

Fields

Authentication

The password goes in the URL, redis://:<password>@<host>:6379/0, or rediss:// for TLS. An Upstash database works with the rediss:// URL its console prints.

Layout

/redis/logs/app.log is the key <prefix>file:/logs/app.log. Folders live in the set <prefix>dir, and modified times in <prefix>modified:<path>.

Behavior

  • Key prefix: a different keyPrefix keeps one workspace’s files apart from another’s, and from other data in the same database.
  • Shared database: the Python, Node, browser and Cloudflare mounts use the same key layout, and the browser store keeps every value byte-identical, so all of them can mount one database at the same time.

Browser

A page cannot open a socket, so @struktoai/mirage-browser reaches Redis through the Upstash REST API. It takes the same redis URL the Upstash console prints: its password is also the REST token. Upstash Redis covers that database on its own page.
  • A read-only token cannot SCAN, which listings need, so mount with the full token.
  • Upstash bills the free and pay-as-you-go tiers per command, and one shell command is several Redis commands (a listing costs a few per entry).
examples/browser/vfs/redis/redis.html mounts a database from a page against Upstash, reading UPSTASH_REDIS_URL from .env.development. examples/browser/vfs/redis/main.ts needs no account: it starts a local HTTP front that speaks the same REST shape over a local redis, mounts it through @struktoai/mirage-browser, and reads every key back through the Node mount to show the two stores agree byte for byte.

Cloudflare

@struktoai/mirage-cloudflare speaks the Redis protocol over the Workers socket API, with a client of its own. It takes the same url, keyPrefix and capacity, so it reaches any Redis, Upstash included, at its redis:// or rediss:// URL.
  • A Worker cannot keep a socket past the request that opened it, so each request opens its own connection; a later command in the same request reuses it.
  • Workers refuse connections to Cloudflare’s own IP ranges.

Integration

Redis answers these commands through its own API, so fewer keys are read. See Integration.
  • find: one recursive listing.
  • du: one recursive listing.
  • ls -R and tree: one recursive listing.

VFS.md

The VFS.md an agent reads with Redis mounted at /<path>. <mode> is the mount’s mode: read, write or exec. The commands shown are those of a write mount.
Virtual FilesystemSupported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.