redisk

A local development Upstash-REST-compatible Redis emulator. In-memory, zero runtime dependencies, wire-compatible with the Upstash REST API — the real @upstash/redis client works against it unmodified.

Run one shared instance for your whole machine so multiple projects never fight over ports or data.

Install

pnpm add -D @sdk-e/redisk   # or npm i -D / yarn add -D

Or run ad hoc:

npx @sdk-e/redisk

Quick start

redisk
# redisk: Upstash-compatible API on http://127.0.0.1:18000 (token: upstash)

Point any Upstash REST client at it:

Variable	Value
KV_REST_API_URL	http://127.0.0.1:18000
KV_REST_API_TOKEN	upstash

import { Redis } from "@upstash/redis";

const redis = new Redis({ url: "http://127.0.0.1:18000", token: "upstash" });
await redis.set("hello", "world");

Library use

Omit the port for an OS-assigned ephemeral instance — perfect for integration tests:

import { startRedisk } from "@sdk-e/redisk";

const server = await startRedisk(); // random free port
// pass server.url + a token of your choosing to your app under test
await server.close();

Wire protocol

• Bearer-token auth (Authorization: Bearer <token>); failures return 401 {"error":"Unauthorized"}.
• POST / with a single JSON command array → one { result | error }.
• POST /pipeline with an array of command arrays → array of { result | error }.
• Path-encoded commands: GET /set/foo/bar ≡ POST / ["set","foo","bar"].
• Honors the upstash-encoding: base64 header on responses.
• Malformed bodies return HTTP 200 with { error } — matching Upstash behavior.
• Unknown routes return 404 {"error":"Not found"}.

Supported commands

PING · ECHO · FLUSHALL · FLUSHDB · GET · SET (EX, PX, NX, XX) · DEL · UNLINK · EXISTS · EXPIRE · PERSIST · TTL · PTTL · INCR · DECR · INCRBY · DECRBY · KEYS

That covers typical web-app usage (caching, counters, rate limiting). Need more? Open an issue — additions must stay protocol-faithful.

Configuration

Variable	Default	Purpose
REDISK_PORT	18000	Listen port (fallback: REDIS_LOCAL_PORT)
REDISK_TOKEN	upstash	Bearer token (fallback: REDIS_LOCAL_TOKEN)
REDISK_HOST	127.0.0.1	Bind interface

CLI flags override env: --port, --token, --host.

Data lives in memory only and disappears when the process exits — by design.

Why port 18000?

Classic local defaults like 6379 collide with real Redis installs; 8000 collides with common dev servers. 18000 keeps a dedicated emulator lane clear even when several SDK-E projects run at once against the shared instance.

Development

Requires Node >= 20 and pnpm >= 11.

pnpm install
pnpm verify     # format, lint, typecheck, test, build

The test suite runs the official @upstash/redis client against the emulator as an integration guarantee.

See CONTRIBUTING.md.

License

MIT