Quickstart

Clone the boilerplate, start it with Docker Compose, and resolve a paused workflow from the dashboard and from the ltc CLI. You need Docker, Node.js and Git.

Run the boilerplate

1. Clone the starter project and install its dependencies.

   git clone https://github.com/hotmeshio/long-tail-boilerplate.git
   cd long-tail-boilerplate
   cp .env.example .env
   npm install

2. Choose the superadmin password. The first boot on an empty database seeds a superadmin account from SEED_ADMIN_PASSWORD. Add it to .env:

   .env

   SEED_ADMIN_PASSWORD=your-own-password

   When the variable is unset, docker-compose.yml supplies a development default (the boilerplate README lists it).

3. Start Postgres, MinIO, NATS and the app.

   docker compose up -d --build

4. Open http://localhost:3030 and sign in as superadmin with the password you set.

Service	Address
Dashboard	http://localhost:3030
REST API	http://localhost:3030/api
MinIO console	http://localhost:9003
Postgres	localhost:5416

Tip

docker compose down -v wipes the database. The next docker compose up -d --build seeds the superadmin again from SEED_ADMIN_PASSWORD.

Look at the example workflows

The boilerplate registers its workflows in src/config/workers.ts, one directory per workflow under src/workflows/.

Workflow	Directory	Shows
helloWorkflow	hello-world/	A timer, an activity and the caller’s identity
reviewContent	content-review/	A confidence score that sends low scores to a moderator form
screenshotResearch	screenshot-research/	A multi-step pipeline with browser and vision tools
assemblyLine	assembly-line/	Stations worked by people in sequence, with parent and child workflows

Open Procedural → Registry in the sidebar to see every registered workflow, and Invoke Tool to start one.

Resolve your first escalation

reviewContent scores a piece of content. Short text and HTML markup score low, and a low score parks the run as an escalation for the content-moderator role.

1. Open Invoke Tool (/workflows/durable/invoke) and pick reviewContent.

2. Enter <b>hi</b> as the content so the analyzer flags it, then start the run.

3. Open All Escalations (/escalations/available) and pick the content-moderator queue. The new row is pending and unclaimed.

4. Open the row and select Claim. The claim locks the row to you for a time window (30 minutes by default) and unlocks the form.

5. Pick a decision and submit. The row is resolved and the workflow completes with your decision.

The form you filled is data: a versioned JSON Schema stored on the content-moderator role. See Forms.

Do the same from the CLI

ltc ships with @hotmeshio/long-tail, so the boilerplate already has it.

1. Sign in. ltc stores a token in ~/.config/longtail/credentials.json.

   export LT_PASSWORD='the password you set'
   npx ltc login --server http://localhost:3030 --username superadmin --password "$LT_PASSWORD"

2. Start a run that will escalate.

   npx ltc wf invoke reviewContent \
     --data '{"contentId":"article-002","contentType":"comment","content":"<b>hi</b>"}'

3. Find the pending row, claim it and resolve it.

   npx ltc esc list --role content-moderator --status pending
   npx ltc esc claim <escalation-id>
   npx ltc esc resolve <escalation-id> --data '{"moderation":{"decision":"approve"}}'

4. Confirm the row is resolved.

   npx ltc esc get <escalation-id>

Every list command takes --json for scripts and -q for ids only.

Next

Write your own wait. Your first conditional builds a review workflow end to end: the activity, the conditional wait, the role’s form and every way to resolve it.

Related

Your first conditionalBuild a workflow that pauses for a person and resumes with a typed answer.

ConceptsEscalation, role, claim, facets and the row lifecycle.

CLIEvery ltc command for escalations, workflows, roles and knowledge.

One row, many resolversThe dashboard, CLI, HTTP, SDK, MCP and MQTT resolve the same row.