Virtualize an Upstash Redis database from Node or the browser.
Upstash serves a Redis database over the Redis protocol
on port 6379 and over a REST API
on the same host. RedisVFS from @struktoai/mirage-node uses the first,
@struktoai/mirage-browser the second, and one URL configures both: the token
Upstash prints is also the database password. Files are laid out as on
Redis, which covers the server side on the
Redis page.
Install
npm install @struktoai/mirage-node redis
Configure
The Upstash console prints a redis-cli line for the database. Its
rediss://default:<token>@<name>.upstash.io:6379 URL is the whole
configuration.
import { MountMode, RedisVFS, Workspace } from '@struktoai/mirage-node'const redis = new RedisVFS({ url: process.env.UPSTASH_REDIS_URL!, keyPrefix: 'mirage/',})const ws = new Workspace({ '/r': redis }, { mode: MountMode.WRITE })const result = await ws.shell('echo hello > /r/greet && cat /r/greet')console.log(result.stdoutText)await ws.close()
Python reaches the same database with the same URL through its
RedisVFS. A mount takes MountMode.READ, WRITE or
EXEC.
Fields
Field
Default
Notes
url
required
The rediss:// URL from the console, password included. Redacted in snapshots.
keyPrefix
mirage:fs:
Prefix of every key the mount reads and writes.
token
from the URL
Browser only. Needed when url is the REST URL (https://<name>.upstash.io) instead of the redis one.
maxRequestBytes
8388608
Browser only. Upstash caps a REST request at 10 MB; a larger file is written as one SET plus APPENDs of this size.
Authentication
Mount with the database’s full token. The console’s read-only token cannot
SCAN, which listings need.
Behavior
One database, both runtimes: the browser store keeps every value
byte-identical to what the Node mount writes, so a page over REST and a
server over the Redis protocol can share one database at the same time. The
Node example
shows the two reading each other’s files.
Billing: the free and pay-as-you-go tiers bill per command, and one shell
command is several Redis commands (a listing costs a few per entry). Worth
knowing before pointing an agent at a metered database.
Browser
The browser mount takes the same URL and talks to the REST API.
npm install @struktoai/mirage-browser
import { MountMode, RedisVFS, Workspace } from '@struktoai/mirage-browser'const redis = new RedisVFS({ url: process.env.UPSTASH_REDIS_URL!, keyPrefix: 'mirage/',})const ws = new Workspace({ '/r': redis }, { mode: MountMode.WRITE })
process.env stands for however the bundler injects the value; the
page example
uses a Vite define fed from UPSTASH_REDIS_URL in .env.development.
That define copies the whole URL, password included, into the served
JavaScript, so the page is a local demo for a trusted machine: run it from
the dev server, do not build or host it. Anyone who reads the token out of a
bundle can call the REST API directly and reach every key, whatever
keyPrefix and mount mode the page used. A page for other people needs a
server-side proxy, or a credential scoped to what that page may touch.