> ## 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.

# Redis

> Virtualize a Redis database from Node or the browser.

`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](https://docs.mirage.strukto.ai/home/setup/redis.md).

## Install

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

## Configure

```ts theme={null}
import { MountMode, RedisVFS, Workspace } from '@struktoai/mirage-node'

const redis = new RedisVFS({
  url: process.env.REDIS_URL!,
  keyPrefix: 'mirage:fs:',
})
const ws = new Workspace({ '/redis': redis }, { mode: MountMode.WRITE })

const result = await ws.shell('echo hello > /redis/note.txt && ls /redis')
console.log(result.stdoutText)
await ws.close()
```

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](https://docs.mirage.strukto.ai/home/setup/vfs.md#mount-capacity). A mount takes `MountMode.READ`,
`WRITE` or `EXEC`.

### Fields

| Field | Default | Notes |
| - | - | - |
| `url` | `redis://localhost:6379/0` | Redis connection URL. Redacted in snapshots. |
| `keyPrefix` | `mirage:fs:` | Prefix of every key the mount reads and writes. |
| `capacity` | none | The most bytes the files may hold, a size like `100MB` or a count of bytes. |

## Authentication

The password goes in the URL, `redis://:<password>@<host>:6379/0`, or
`rediss://` for TLS. An [Upstash](https://docs.mirage.strukto.ai/typescript/vfs/upstash.md) database works with
the `rediss://` URL its console prints.

## Layout

```text theme={null}
/redis/
  config.json
  logs/
    app.log
  cache/
    session-abc.json
```

`/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](https://upstash.com/docs/redis/features/restapi).
It takes the same redis URL the Upstash console prints: its password is also
the REST token. [Upstash Redis](https://docs.mirage.strukto.ai/typescript/vfs/upstash.md) covers that database
on its own page.

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

```ts theme={null}
import { MountMode, RedisVFS, Workspace } from '@struktoai/mirage-browser'

const redis = new RedisVFS({
  url: 'rediss://default:<token>@<name>.upstash.io:6379',
  keyPrefix: 'mirage:fs:',
})
const ws = new Workspace({ '/redis': redis }, { mode: MountMode.WRITE })
```

* 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).

> [accordion] Browser fields
>
> | Field | Default | Notes |
> | - | - | - |
> | `url` | required | The database's redis URL, password included; or its REST URL (`https://<name>.upstash.io`) with `token` beside it. Redacted in snapshots. |
> | `token` | from the URL | The REST token. Needed only with a REST URL, as for a self-hosted [serverless-redis-http](https://github.com/hiett/serverless-redis-http) front, whose token is not a redis password. |
> | `keyPrefix` | `mirage:fs:` | Prefix of every key the mount reads and writes. |
> | `maxRequestBytes` | `8388608` | Upstash caps a request at 10 MB; a larger file is written as one `SET` plus `APPEND`s of this size. |
> | `capacity` | none | The most bytes the files may hold. |

> [accordion] Examples
>
> [`examples/browser/vfs/redis/redis.html`](https://github.com/strukto-ai/mirage/blob/main/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`](https://github.com/strukto-ai/mirage/blob/main/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.

```ts theme={null}
import { MountMode, RedisVFS, Workspace } from '@struktoai/mirage-cloudflare'

const redis = new RedisVFS({ url: env.REDIS_URL, keyPrefix: 'mirage:fs:' })
const ws = new Workspace({ '/redis': redis }, { mode: MountMode.WRITE })
```

* 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](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `find`: one recursive listing.
* `du`: one recursive listing.
* `ls -R` and `tree`: one recursive listing.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.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.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `<mode>` |
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Almost all Unix commands. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `<mode>` |
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Almost all Unix commands. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ```


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