Quickstart

Or start from a sample

Not ready to point Carbon at your own spec yet? Every install ships with a curated catalog of real API subsets you can boot locally.

From the CLI:

carbon emulate --catalog stripe

Available catalog entries include stripe, github, openai, slack, twilio, notion, linear, and shopify.

The catalog is useful for a first smoke test because it exercises the same stateful runtime path as your own OpenAPI, AsyncAPI, GraphQL, protobuf/gRPC, HAR, or Postman input.

1. Install

The fastest path is the one-line installer — it fetches the latest standalone binary for your OS and architecture, verifies its SHA-256, and installs it to ~/.local/bin (no sudo, no Node):

curl -fsSL https://carbon-web-psi.vercel.app/install.sh | sh

Pin a specific release with CARBON_VERSION=v0.3.0 or pass it as a flag:

sh -c "$(curl -fsSL https://carbon-web-psi.vercel.app/install.sh)" -- --version v0.3.0

The CLI also publishes to npm as carbon-api (installs a carbon executable, with carbon-api and carbon-dev as aliases), and to Homebrew as carbon-dev/carbon/carbon:

npm install -g carbon-api
# or
brew install carbon-dev/carbon/carbon

Or without a global install:

npx carbon-api <command>

2. Initialize a project

mkdir petstore && cd petstore
carbon init --name petstore

That writes a carbon.config.ts you can edit later — project name, slug, runtime port. Re-running carbon init in the same directory prompts before overwriting (use --force in scripts).

3. Ingest a spec

Any supported description works — OpenAPI, AsyncAPI, GraphQL SDL, protobuf, HAR, or a Postman collection. Carbon parses it into its Intermediate Representation and prints a summary.

carbon ingest ./petstore.openapi.json

Parsed petstore v1.0.0
Endpoints     14
Resources     3
Relationships 2

4. Boot the runtime

carbon emulate --from ./petstore.openapi.json --port 4000

The replica listens on http://localhost:4000. Health, inspection, and state routes live under /__carbon/*. Pass --watch to auto-reload on spec changes.

5. Hit it like a real API

curl -X POST http://localhost:4000/pets \
  -H 'content-type: application/json' \
  -d '{"name":"Milo","tag":"cat"}'

curl http://localhost:4000/pets
# → the pet you just created is in the list

State survives across requests because Carbon compiled the spec into a behavior graph — it isn’t returning canned JSON.

6. Snapshot the state

carbon snapshot save baseline

Snapshots land under .carbon/snapshots/ as JSON. Restore any time:

carbon snapshot load baseline

That’s the whole loop: ingest → emulate → mutate → snapshot → restore.

Next steps

Spec to runtime — how ingest, IR, and the behavior graph fit together.
State engine — snapshots, journal, rewind.
Chaos — latency and error injection for resilience tests.
CLI reference — every command and flag.