OpenSim

Open-source API behavior simulator: turn OpenAPI specs into realistic, stateful API experiences — no handcrafted mock fixtures required.

Quick start

The fastest way to see OpenSim in action is the bundled example:

make run-example

See examples/payment-flow/README.md for a full walkthrough (create a payment, poll it through its lifecycle, list, reset) with real request/response output.

Install

curl -fsSL https://raw.githubusercontent.com/blorenzo10/open-sim/main/install.sh | sh

Requires Node.js 20+. The installer downloads the release tarball, verifies its SHA-256 checksum, unpacks it to ~/.local/share/open-sim, and symlinks the binary into ~/.local/bin.

Piping a script to sh means executing code you have not read. To review it first — recommended, and no harder:

curl -fsSLO https://raw.githubusercontent.com/blorenzo10/open-sim/main/install.sh
less install.sh
sh install.sh

Overrides: OPEN_SIM_VERSION (pin a version), OPEN_SIM_HOME (install directory), OPEN_SIM_BIN_DIR (symlink directory).

Then:

open-sim run path/to/openapi.yaml --port 4010

Uninstall with rm -rf ~/.local/share/open-sim ~/.local/bin/open-sim.

Releasing

Artifacts are built and published by .github/workflows/release.yml when a v* tag is pushed. The workflow refuses to publish if the tag disagrees with package.json, and runs scripts/smoke-release.sh — which installs the freshly built tarball and drives the real binary — before uploading. Build and verify locally with make release and make smoke-release.

Using the open-sim command

To get open-sim on your PATH and use it like an installed CLI:

make link          # build + symlink `open-sim` globally
open-sim run path/to/openapi.yaml --port 4010 --seed 42
open-sim validate path/to/openapi.yaml
make unlink        # remove it again

make smoke verifies the linked binary actually runs. Prefer make link over make run when you want to exercise the CLI the way a real user does: make run invokes node dist/cli/index.js directly and bypasses the bin symlink, so it cannot catch entrypoint or packaging breakage.

OpenSim is not on npm or Homebrew; the installer above is the supported route.

Makefile utilities

A Makefile wraps the common commands so you never need to call pnpm/node directly. Run make help to list everything; the main targets:

Command	What it does
make install	Install dependencies
make build	Compile TypeScript to dist/
make link / make unlink	Add/remove the global open-sim command
make smoke	Verify the linked binary actually runs
make release	Build the distributable tarball + checksum
make smoke-release	Install the tarball to a temp prefix and drive it
make run-example	Run the bundled payment-flow example
make run SPEC=path/to/openapi.yaml	Build and run OpenSim against your own spec
make dev SPEC=path/to/openapi.yaml	Run from source (no build step, via tsx)
make validate SPEC=path/to/openapi.yaml	Validate a spec without serving it
make test / make test-watch	Run the test suite
make lint	ESLint + module-boundary checks
make typecheck	Type-check the project
make check	Lint + typecheck + test in one shot
make clean	Remove dist/ and the AI enrichment cache

SPEC, SEED, and PORT are overridable on any run target, e.g.:

make run SPEC=my-api.yaml SEED=42 PORT=8080

Docs

• docs/product-discovery.md — product positioning, MVP scope, success criteria.
• docs/technical-design.md — architecture and module boundaries.