SQLite State

Persist approval requests with file-backed SQLite on a single Node process. 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 SqliteState as the state option in new Hitl().

SQLite fits local development and single-process deploys. State lives on the server only; workflow code never touches the database directly. See Overview for the two-process split.

Requires Node.js 22.13+ (node:sqlite).

Install

Install the core Hitl SDK and the SQLite state package. Pick a workflow engine resolver separately; see Workflow Engines.

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

Set up the Hitl server with SQLite

Constructing SqliteState runs migrations automatically when the database opens. No separate migration step is required for most apps. Create a directory for the database file, then wire SqliteState into new Hitl().

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

import { mkdirSync } from "node:fs";
import { join } from "node:path";
import { DatabaseSync } from "node:sqlite";
import { Hitl } from "@hitl-sdk/hitl";
import { SqliteState } from "@hitl-sdk/state-sqlite";
import { workflowResolver } from "@hitl-sdk/resolver-workflow-sdk";

const dbPath = join(process.cwd(), ".hitl", "human_requests.db");
mkdirSync(join(process.cwd(), ".hitl"), { recursive: true });

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

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

CLI (optional)

Initialize a database outside your app when CI, scripts, or infra runs before the server starts:

npx @hitl-sdk/state-sqlite setup --db .hitl/human_requests.db
npx @hitl-sdk/state-sqlite schema   # export DDL without opening a database

Use schema when you want to review or hand-apply DDL instead of opening a file at runtime.

When to use something else

SQLite is file-backed and tied to one Node process. Choose a different backend when:

• Multi-replica production: use Postgres or Redis so every server instance reads the same pending requests
• Throwaway local demo: omit state or use InMemoryState from @hitl-sdk/hitl/state (requests reset on restart)

Migrations

Schema changes are versioned inside @hitl-sdk/state-sqlite. Opening the database applies new migrations idempotently after you upgrade the package. No manual DDL is required unless you use the CLI to export schema for review.