Redis State

Persist approval requests in Redis when you already run Redis for caching or sessions. When a workflow POSTs to your Hitl server, the server records the request in state and keeps it until someone resolves or times out. Pass IoredisState as the state option in new Hitl().

Redis fits multi-replica servers and low-latency lookups. State lives on the server only; workflow code never touches Redis directly. See Overview for the two-process split.

Install

Install the core Hitl SDK, the Redis state package, and ioredis. You construct and own the Redis connection. Pick a workflow engine resolver separately; see Workflow Engines.

npm i @hitl-sdk/hitl @hitl-sdk/state-ioredis ioredis

Set up the Hitl server with Redis

Migrations run on first operation, or call ensureSchema() explicitly at deploy time. Connect to your Redis instance, wrap the client in IoredisState, and pass it to new Hitl().

Create lib/hitl.ts and paste the following. Swap workflowResolver() for your engine; the state setup stays the same.

import Redis from "ioredis";
import { Hitl } from "@hitl-sdk/hitl";
import { IoredisState } from "@hitl-sdk/state-ioredis";
import { workflowResolver } from "@hitl-sdk/resolver-workflow-sdk";

const redis = new Redis(process.env.REDIS_URL);
const state = new IoredisState(redis);
await state.ensureSchema();

export const hitl = new Hitl({
  state,
  resolver: workflowResolver(),
});

You still need to register /.well-known/hitl/v1 on your HTTP server. See Host integration or your workflow engine page.

Custom key prefix

Use a custom prefix when multiple apps share one Redis cluster and you need to isolate keys:

const state = new IoredisState(redis, { tableName: "custom_approvals" });
// Redis keys are prefixed with `custom_approvals:`

The option name matches SQL backends (tableName) even though Redis uses key prefixes, not tables.

Key layout

Default prefix: hitl:human_requests (from table name hitl.human_requests).

No setup CLI. Migrations run in-process against your Redis instance when you call ensureSchema() or on the first state operation.

Migrations

Upgrade @hitl-sdk/state-ioredis and call ensureSchema() (or let the first operation apply pending migrations). Keys are updated idempotently; you do not need to flush Redis on upgrade.