> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upstash Redis

> Virtualize an Upstash Redis database from Node or the browser.

[Upstash](https://upstash.com) serves a Redis database over the Redis protocol
on port 6379 and over a [REST API](https://upstash.com/docs/redis/features/restapi)
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](https://docs.mirage.strukto.ai/typescript/vfs/redis.md), which covers the server side on the
[Redis page](https://docs.mirage.strukto.ai/home/setup/redis.md).

## Install

```bash theme={null}
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.

```ts theme={null}
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`](https://docs.mirage.strukto.ai/python/vfs/redis). 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 `APPEND`s 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](https://github.com/strukto-ai/mirage/blob/main/examples/browser/vfs/redis/main.ts)
  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.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
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](https://github.com/strukto-ai/mirage/blob/main/examples/browser/vfs/redis/redis.html)
uses a Vite `define` fed from `UPSTASH_REDIS_URL` in `.env.development`.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.