Skip to main content

Getting Started

Workloom is a package manager and desired-state tool for AI workflow assets. It validates workspace manifests, renders provider-specific files, applies approved outputs, ingests privacy-safe telemetry, and exposes a typed API with a React management UI.

Prerequisites​

  • Node.js 22 or newer.
  • pnpm 9.x.
  • Git.

Check your local tools:

node --version
pnpm --version
git --version

Install​

pnpm install

Run the Full Dev Stack​

# Start the API server (port 4050)
pnpm api:start

# Start the web app (port 3050, proxies API)
pnpm web:start

The web app is available at http://localhost:3050. It authenticates via OIDC against the API server and provides a management dashboard for packages, workspaces, telemetry, and approvals.

Prove the Local CLI Loop​

pnpm typecheck
pnpm lint
pnpm test
pnpm wl validate fixtures/workspaces/simple-workspace.json
pnpm wl render --workspace fixtures/workspaces/simple-workspace.json --dry-run
pnpm wl sync --check --workspace fixtures/workspaces/simple-workspace.json

The dry-run render prints planned Claude, Codex, and Copilot files. It does not write provider output or local state.

Apply Into the Sandbox​

Use the committed Copilot projection fixture to prove approval-gated writes:

pnpm wl sync --workspace fixtures/workspaces/committed-copilot-projection.json --approve-local

Or use the interactive approval prompt:

pnpm wl sync --workspace fixtures/workspaces/committed-copilot-projection.json --interactive-approval

This writes under .workloom/sandboxes/copilot-commit/, then records:

  • .workloom/state/render-plan.json
  • .workloom/state/approvals.json

The sandbox is ignored by Git.

Expected Failure Example​

Policy-denied hooks must fail before writes:

pnpm wl sync --check --workspace fixtures/workspaces/policy-denied-hooks.json

Expected result: non-zero exit with trust.denied_hook.

Publish a Draft Package​

pnpm wl push --draft --package fixtures/packages/workloom-baseline-v1.json

The command hashes selected package assets. It does not upload arbitrary workspace folders.

Regenerate the API Client​

After modifying API routes, regenerate the typed client:

pnpm --filter @workloom/workloom-api generate
pnpm --filter @workloom/workloom-api generate:check

See Developer Workflow for the full generation pipeline.

Build for Production​

pnpm build

This builds all packages, the API server, and the web app static assets (apps/web/dist/).