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
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
keyPrefixkeeps 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).
Browser fields
Browser fields
Examples
Examples
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 -Randtree: 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.
- Rendered
- Raw
Virtual Filesystem
Supported 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.