Setup

little setup is the guided way to start a project. It ships with Little Workflow, published on npm as @little-stack/workflow 0.2.0-alpha.2 (3 November 2026) on the alpha and latest tags. It always includes a Little Harness agent. A sample durable Little Workflow is optional.

This page is the canonical setup guide. The full command and flag reference is Workflow CLI → Setup.

Requirements

• Node.js 22 or newer.
• AI SDK 7. ai is a peer dependency (^7.0.0) of both @little-stack/harness and @little-stack/workflow, and you add an AI SDK 7 provider package for your models.
• With pnpm 10, allow the better-sqlite3 native build that Little Workflow's Local World event store uses. pnpm skips dependency build scripts unless you allow them:

{
  "pnpm": { "onlyBuiltDependencies": ["better-sqlite3"] }
}

setup or init

Three commands create projects. Pick by what you want to end up with.

New project

# Interactive Next.js or standalone Node agent wizard
npx @little-stack/workflow@alpha setup

The command synopsis is little setup [directory | --here] [--template node|next|existing-next] [--workflow]. Run setup --help for provider, model, package manager, route, page, installation and verification options.

Existing Next.js app

Preview first, then apply:

# Preview additive changes in an existing TypeScript App Router project
npx @little-stack/workflow@alpha setup --here --template existing-next --workflow --plan

# Apply, explicitly allow the SQLite native build, and run keyless verification
npx @little-stack/workflow@alpha setup --here --template existing-next --workflow --yes --install --allow-native-build --verify

Leave out --workflow to add only the Harness agent. --plan previews the changes without writing. --install installs dependencies, --allow-native-build explicitly allows the SQLite native build, and --verify runs a keyless verification.

--here always means the current directory and no longer selects the existing-app mode, so pass --template existing-next as above to add Little to an existing Next.js app. A new-project template (node, the default, or next) needs an empty target. The default provider is openai in little setup, little init and little-harness init, and little init names its workflow with --workflow-name <name>.

What setup does

Setup detects app/ or src/app/, places agent definitions beside the app, preserves routes, scripts, configuration and environment files, and rejects conflicts before writing. Rerunning the same choices is a no-op. It disables dependency lifecycle scripts and journals its writes so an interrupted run can be recovered.

Before you go to production

• The default demo is keyless. It makes no model calls; real model calls are opt-in.
• Add real authentication. Live production chat requires application authentication; replace the generated sample authentication assumptions. The generated LITTLE.md describes the authentication and local persistence assumptions.
• Replace local storage. The generated filesystem and SQLite persistence is for local development.
• LittleDB and workspaces beyond your machine are not part of setup. Neither is published on npm.

Recover an interrupted setup

Stop the installer first, then run rollback for the same project:

# Recover CLI-owned files after an interrupted transaction
npx @little-stack/workflow@alpha setup --here --rollback --yes

Rollback restores unchanged CLI-written content and preserves concurrent edits.

--rollback needs a project directory or --here, the interrupted-setup error prints the exact recovery command, and recovery reports one of four outcomes. The library API is recoverSetup(), which can throw for an invalid journal or a still-running installer. See Setup Recovery.

Next steps

• Harness: Embedding in Your App to configure the agent setup created.
• Workflow Quickstart to define and run your own workflow.
• How they fit for what each product owns.