Install and run a workflow

This guide creates a factory, starts its service and runs hello, the workflow every new factory includes.

Set up with a coding agent

The fastest way to get started is to let your coding agent do the setup. Install the jigs skill:

npx skills add salimhamed/jigs

Then ask your agent:

/jigs set up a factory in this empty directory

The rest of this page shows the same process manually.

1. Prerequisites

• Node.js 24.22.1 or newer
• pnpm
• Docker, with Docker running

hello doesn't use a model, a coding agent or any provider, so you don't need model credentials, agent CLIs or a hub yet. A factory reaches GitHub, Linear, Slack and PagerDuty through a hub, which you connect once a workflow uses one: see hub.

2. Create a factory

mkdir my-factory
cd my-factory
git init
pnpm dlx @jigs-ai/jigs init

Recently published versions

jigs is changing rapidly. If pnpm's minimum release age setting holds back a recent release, use this variant to exempt jigs from that restriction:

pnpm --config.minimum-release-age-exclude=@jigs-ai/jigs dlx @jigs-ai/jigs init

The exception applies only to jigs. It does not refresh pnpm's dlx cache.

init writes the starting files without starting the service. workflows/hello/hello.ts contains your first workflow, and jigs.config.ts registers it under the name hello.

3. Set up the environment

pnpm install
cp .env.example .env
cp .env.local.example .env.local

.env holds values every copy of the factory shares, such as API keys. .env.local holds this copy's own, such as the ports jigs init suggested. hello needs nothing else. See The environment.

4. Start the service

pnpm exec jigs up

jigs up starts everything your factory needs and checks that it is ready. When it finishes, the service and dashboard are available. Open the dashboard URL it prints to inspect workflow runs and individual steps.

5. Run hello

pnpm exec jigs run hello

jigs run hello starts the workflow in the jigs service and gives you a run ID and dashboard link. The workflow continues independently of the command that started it. Use the dashboard or jigs status to check its progress:

pnpm exec jigs status

Wait for the run to show as completed.

That's it. You now have a running jigs factory and have completed your first workflow.

When you're finished, stop the factory:

pnpm exec jigs down