API & SDK reference

Molar Clones exposes three API layers: vendor-shaped APIs (what your app calls), admin APIs (clock, snapshots, chaos), and the Molar API (spawn, world snapshot, fleet). The TypeScript SDK wraps all three.

npm packages

Package	Purpose
`@molar/clones`	Umbrella — `stripe`, `twilio`, `email`, `auth`, `s3`, `world`
`@molar/clones-core`	`CloneBase`, refusal, binary install
`@molar/clones-stripe`	Stripe-only import
`@molar/clones-twilio`	Twilio-only import
`@molar/clones-email`	Email-only import
`@molar/clones-auth`	Auth-only import
`@molar/clones-s3`	S3-only import
`@molar/clones-playwright`	Playwright fixtures
`@molar/clones-mcp`	MCP server tools
`@molar/cli`	npm wrapper for `molar` native binary

TypeScript SDK — `CloneBase`

Every *.start() returns a CloneBase instance plus kind-specific helpers.

`start(options?)`

type StartOptions = {
  seed?: string;           // default "molar-sdk-seed" — drives deterministic IDs
  runId?: string;          // default random
  url?: string;            // BYOC — skips spawn
  adminUrl?: string;
  adminToken?: string;
  key?: string;
  testKey?: string;
  clockFreezeAt?: string;  // ISO timestamp
};

Instance properties

Property	Description
`kind`	`stripe` \| `twilio` \| `email` \| `auth` \| `s3`
`runId`	Tenant partition ID
`url`	Vendor API base (TLS in library mode)
`adminUrl`	Admin API base
`key` / `testKey`	Derived vendor credential

Instance methods

Method	Admin endpoint
`advanceClock(duration)`	`POST /_clone/clock/advance`
`injectError(rule)`	`POST /_clone/inject/error`
`injectLatency(rule)`	`POST /_clone/inject/latency`
`injectRateLimit(rule)`	`POST /_clone/inject/ratelimit`
`snapshot()`	`POST /_clone/snapshot/{runId}/save` → `Uint8Array`
`restore(blob)`	`POST /_clone/snapshot/{runId}/restore`
`expectWebhookFired(type, ms?)`	Poll webhook events
`stop()`	SIGTERM child process
`request(path, init)`	Vendor API via `/t/{runId}{path}`
`adminGet(path)` / `adminPost(path, body)`	Admin API

Kind-specific helpers

Stripe: testKey, publishableKey, seedData(), createPaymentMethod(), createPaymentIntent(), listCustomers(), expectWebhookFired()

Twilio: createMessage(), createVerification(), checkVerification(), lastOTP()

Email: send(), inbox(), markBounce(), markSpamTrap()

Auth: seedUsers(), createUser(), signIn(), jwks()

S3: endpoint, accessKeyId, secretAccessKey, createBucket(), putObject(), getObject(), list(), putBucketLifecycle()

World API

import { world } from "@molar/clones";

const registry = world.localRegistry([stripeClone, emailClone]);
await world.snapshot(registry, runId, "checkpoint");
await world.restore(registry, runId, "checkpoint");

Environment variables

Variable	Description
`MOLAR_CLONE_{KIND}_URL`	Service-mode API URL (`STRIPE`, `TWILIO`, `EMAIL`, `AUTH`, `S3`)
`MOLAR_CLONE_{KIND}_ADMIN_URL`	Admin URL
`MOLAR_CLONE_{KIND}_ADMIN_TOKEN`	Admin bearer token
`MOLAR_CLONE_{KIND}_TLS_CA_FILE`	PEM for private TLS CA
`MOLAR_CLONE_{KIND}_BIN`	Override Go binary path
`MOLAR_CLONE_ADMIN_TOKEN`	Global admin token
`MOLAR_CLONE_BIN_DIR`	Binary search directory
`MOLAR_CLONE_BINARY_CACHE_DIR`	Cached release binaries
`MOLAR_CLONES_CTRL_URL`	Molar API base URL
`MOLAR_CLONES_API_TOKEN`	Molar API API key
`MOLAR_DESTRUCTIVE_ALLOW`	`1` to disable live-vendor refusal (dangerous)

Kind env suffixes: STRIPE, TWILIO, EMAIL, AUTH, S3.

Go binaries

Binary	Role
`clones-stripe`	Stripe API + admin
`clones-twilio`	Twilio API + admin
`clones-email`	Email API + admin
`clones-auth`	Clerk-shaped API + admin
`clones-s3`	S3 API + admin
`clones-control`	Spawn, world snapshot, sessions
`clones-fixture`	All fixture vendors
`route-proxy`	Host-based routing + refusal
`molar`	CLI (`molar clones spawn`, `list`, …)

Common env vars for binaries:

MOLAR_CLONE_ADDR=127.0.0.1:8000
MOLAR_CLONE_TLS_ADDR=127.0.0.1:8443
MOLAR_CLONE_ADMIN_ADDR=127.0.0.1:9000
MOLAR_CLONE_SEED=demo
MOLAR_CLONE_CLOCK_FREEZE_AT=2026-01-01T00:00:00Z
MOLAR_CLONE_ADMIN_TOKEN=

Molar API REST API

OpenAPI spec: molar-clones/docs/openapi/control-plane.json

Sessions & spawn

Method	Path	Description
`POST`	`/api/clones/{kind}/spawn`	Spawn clone → `{ runId, url, adminUrl, expiresAt }`
`DELETE`	`/api/clones/{runId}`	Teardown session
`POST`	`/api/clones/start`	Start persistent session
`GET`	`/api/sessions`	List active sessions

World operations

Method	Path	Description
`POST`	`/api/clones/world/snapshot`	`{ runId, name }`
`POST`	`/api/clones/world/restore`	`{ runId, name }`
`GET`	`/api/clones/world/restore/{restoreId}`	Async restore status
`POST`	`/api/clones/world/clock/advance`	Advance all registered clones

Observability & chaos

Method	Path	Description
`GET`	`/api/clones/{runId}/health`	Session health
`GET`	`/api/clones/{runId}/logs?since=`	SSE request log tail
`POST`	`/api/clones/{runId}/inject`	Fault injection
`GET`	`/api/traces/{runId}`	Ordered call + mutation trace

Fleet

Method	Path	Description
`POST`	`/api/clones/register`	Register BYOC backend
`PUT`	`/api/route/config`	Route proxy host → session mapping
`POST`	`/api/seeds/apply`	Apply named seed to session

Per-clone admin API (`:9000`)

Method	Path	Description
`POST`	`/_clone/seed`	Seed initial state
`POST`	`/_clone/reset/{runId}`	Reset tenant
`POST`	`/_clone/snapshot/{runId}/save`	Save snapshot (gzip body)
`POST`	`/_clone/snapshot/{runId}/restore`	Restore snapshot
`POST`	`/_clone/clock/advance`	`{ duration: "30d" }`
`POST`	`/_clone/clock/set`	Set absolute time
`POST`	`/_clone/clock/pause`	Pause
`POST`	`/_clone/clock/resume`	Resume
`POST`	`/_clone/inject/error`	Chaos error rule
`POST`	`/_clone/inject/latency`	Chaos latency rule
`GET`	`/_clone/log/{runId}`	NDJSON request log
`GET`	`/_clone/health`	Health
`GET`	`/_clone/ready`	Readiness

Vendor-specific admin paths: /_clone/stripe/events/, /_clone/twilio/otp/, /_clone/email/inbox/, etc.

MCP tools

Canonical connector tools (org-scoped via API key):

Tool	Description
`molar_clone_spawn`	Spawn session → id + endpoint
`molar_clone_list`	List org sessions
`molar_clone_seed`	Apply named seed
`molar_clone_snapshot`	Save snapshot (base64)
`molar_clone_restore`	Restore from base64
`molar_clone_world`	World snapshot or restore
`molar_clone_route`	Route proxy config
`molar_clone_trace`	Session call trace
`molar_clone_stop`	Teardown session
`molar_clone_advance_clock`	Advance clock
`molar_clone_inject_error`	Error injection
`molar_clone_start`	Legacy spawn alias

Vendor helpers: stripe_advance_clock, stripe_expect_webhook, twilio_last_otp, email_inbox, email_mark_bounce, auth_seed_users, s3_create_bucket, s3_put, s3_list, world_snapshot, world_restore.

Full manifest: docs.molar.it/.well-known/molar-capabilities.json

Molar runtime (`@molar/runtime`)

import { molar } from "@molar/runtime";

await molar.clones.start([{ kind: "stripe", seed: "x" }]);
molar.clones.stripe;           // running instance
await molar.clones.fault.inject(pattern, opts);
await molar.clones.clock.advance(ms);
await molar.clones.stopAll();

Type generation

Stripe/Twilio types auto-regenerated from vendor OpenAPI:

cd molar-clones && npm run regen:types

Dashboard Settings → API drift shows regen status.

Errors

Error	Cause
`MolarDestructiveCallError`	Live vendor URL + live key pattern
`MolarUnknownTargetError`	Missing `X-Molar-Clone` response header
`MOLAR_E020`–`E023`	Molar runtime clone errors

See Troubleshooting and Error codes.

BYOC & fleet Troubleshooting

API & SDK reference

API & SDK reference

npm packages

TypeScript SDK — CloneBase

start(options?)

Instance properties

Instance methods

Kind-specific helpers

World API

Environment variables

Go binaries

Molar API REST API

Sessions & spawn

World operations

Observability & chaos

Fleet

Per-clone admin API (:9000)

MCP tools

Molar runtime (@molar/runtime)

Type generation

Errors

TypeScript SDK — `CloneBase`

`start(options?)`

Per-clone admin API (`:9000`)

Molar runtime (`@molar/runtime`)