Quickstart (local)

Run your first Fabric Experiment in 60 seconds — no SaaS, no signup, no infrastructure.

This guide walks you from zero to a running experiment with a deterministic assignment and a real exposure record — entirely on your laptop. No account, no Cloudflare, no database. Just the fx CLI and a YAML file.

Every command below is covered by the repository's fresh-project smoke (pnpm run smoke:new-project), which creates a clean temporary project and runs the same flow end to end.

The primary snippets use Bash (macOS, Linux, WSL, or Git Bash). Native Windows PowerShell equivalents are included for the commands whose syntax differs.

1. Install

npm install -g @fabricorg/experiments
fx --help

(If you can't install globally, prefix everything with npx @fabricorg/experiments.)

2. Create one experiment

mkdir my-fx && cd my-fx
mkdir experiments

New-Item -ItemType Directory -Path my-fx | Out-Null
Set-Location my-fx
New-Item -ItemType Directory -Path experiments | Out-Null

Save this as experiments/homepage-cta.yaml:

id: homepage-cta
name: Homepage CTA copy test
sampleRate: 1
variants:
  - key: control
    name: Get started
  - key: treatment
    name: Start free trial
metrics:
  - key: signup
    name: Sign-ups
    kind: conversion
    eventName: signup
    isPrimary: true

3. Run it

fx dev &                          # starts an in-process control plane on :8787
fx plan experiments/              # previews the create/update/delete diff
fx apply experiments/             # validates + creates the experiment
fx publish                        # signs the manifest

In PowerShell, keep fx dev in a second terminal, then run the other three commands in the first terminal. fx plan uses detailed exit codes: 0 means no changes, 2 means a valid plan has changes, and 1 means an error. An exit code of 2 is expected on this first run; do not chain it with &&.

You'll see:

✓ experiments/homepage-cta.yaml  (homepage-cta)
1 experiment(s) valid.
Summary: +1 create, ~0 update, -0 delete.
Signed manifest v1 (keyId=dev-default, contentHash=…) written to .fx/manifest.json

The signed manifest is now served at http://127.0.0.1:8787/manifest.

4. Pretend to be a user

# Record an exposure (your app would do this from the SDK).
curl -X POST http://127.0.0.1:8787/v1/exposure \
  -H 'content-type: application/json' \
  -d '{"experimentId":"homepage-cta","subjectId":"alice","variantKey":"treatment","manifestVersion":1}'

# Record a conversion.
curl -X POST http://127.0.0.1:8787/v1/conversion \
  -H 'content-type: application/json' \
  -d '{"subjectId":"alice","eventName":"signup","value":1}'

PowerShell uses native JSON request objects, avoiding shell-quoting differences:

Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8787/v1/exposure `
  -ContentType 'application/json' `
  -Body (@{
    experimentId = 'homepage-cta'; subjectId = 'alice'
    variantKey = 'treatment'; manifestVersion = 1
  } | ConvertTo-Json)

Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8787/v1/conversion `
  -ContentType 'application/json' `
  -Body (@{ subjectId = 'alice'; eventName = 'signup'; value = 1 } | ConvertTo-Json)

5. See results

fx report homepage-cta

Output:

homepage-cta — Homepage CTA copy test
  variant      exposed   converted   cr     lift
  control            0           0   0.00%   —
  treatment          1           1  100.00%  +inf%

Real data needs more than one user — but you've now exercised every link in the chain: YAML → governed action → signed manifest → assignment → exposure → conversion → report.

6. Tear it down

fx kill homepage-cta --reason "demo done"
kill %1   # stop fx dev

In PowerShell, press Ctrl+C in the terminal running fx dev.

Killing emits a governed event (visible in the audit log) and removes the experiment from the live manifest.

What just happened

Where to next

Run on a marketing site, no app code → Tag-loader guide
Add the SDK to your app → Web SDK reference
Verify the same path in CI → run pnpm run smoke:new-project from a repository checkout.
All YAML fields with examples → YAML schema reference
Move to staging / production → Provision staging or Self-host on a static CDN
Coming from Mojito JS Delivery? → Migration guide

On this page