BYOC & fleet deployment

Bring Your Own Clone (BYOC) lets platform teams run long-lived clone endpoints in their own infrastructure while developers and CI connect via MOLAR_CLONE_*_URL environment variables. The same Go binaries power laptop library mode, cloud-hosted sandboxes, and on-prem Helm fleets.

Deployment modes compared

Library mode (default)

No configuration required. import { stripe } from "@molar/clones" spawns clones-stripe locally.

Override binary location:

export MOLAR_CLONE_STRIPE_BIN=/opt/molar/clones-stripe
export MOLAR_CLONE_BIN_DIR=~/.cache/molar/binaries

Embedded binaries can be cached via @molar/clones-core postinstall when release artifacts are available; local dev often uses go run or MOLAR_CLONE_BIN_DIR.

Service / BYOC mode

Register endpoints in the dashboard Fleet page or set env vars:

export MOLAR_CLONE_STRIPE_URL="https://clones.internal.example.com/stripe"
export MOLAR_CLONE_STRIPE_ADMIN_URL="https://clones.internal.example.com/stripe-admin"
export MOLAR_CLONE_STRIPE_ADMIN_TOKEN="your-admin-token"

export MOLAR_CLONE_TWILIO_URL="..."
export MOLAR_CLONE_EMAIL_URL="..."
export MOLAR_CLONE_AUTH_URL="..."
export MOLAR_CLONE_S3_URL="..."

The SDK skips spawning when url is set (explicitly or via env):

const clone = await stripe.start({ runId: "ci-job-42" });
// Uses MOLAR_CLONE_STRIPE_URL automatically

TLS: set MOLAR_CLONE_STRIPE_TLS_CA_FILE for private CAs.

Molar API URL

For hosted-style spawn/teardown against your fleet:

export MOLAR_CLONES_CTRL_URL="https://clones-control.internal.example.com"
export MOLAR_CLONES_API_TOKEN="org-api-key"

Used by MCP solo mode and platform API integrations.

Run one clone manually

MOLAR_CLONE_ADDR=127.0.0.1:8000 \
MOLAR_CLONE_ADMIN_ADDR=127.0.0.1:9000 \
MOLAR_CLONE_SEED=production-parity \
MOLAR_CLONE_ADMIN_TOKEN=change-me \
go run ./cmd/clones-stripe

Multi-clone convention: API ports 8001–8006, admin = API + 1000.

Molar API

go run ./cmd/clones-control

Orchestrates spawn, world snapshot/restore, session auth.

Route proxy

go run ./cmd/route-proxy
# PROXY_LISTEN_ADDR default :8443

Transparently routes api.stripe.com → clone with live-vendor refusal.

Docker images

make images
# molar/clones-{stripe,twilio,email,auth,s3,control}:dev

Images: ghcr.io/molar/clones-{kind}:vX.Y.Z — multi-arch linux/amd64 + linux/arm64.

Helm install (on-prem)

helm upgrade --install molar-clones deploy/helm/molar-clones-bundle \
  --namespace molar-clones \
  --create-namespace \
  --set networkPolicy.denyEgress=true \
  --set telemetry.enabled=false

Bundle includes: five clone deployments, Molar API, Postgres, Redis, optional Garage snapshot store.

Prerequisites

• Kubernetes cluster with isolated namespace
• Signed images, Cosign signatures, SBOM from release tag
• Customer-approved storage for Postgres, Redis, snapshot store
• DNS/ingress approved by network team

Air-gap bundle

# Build/obtain offline bundle
deploy/air-gap/bundle.sh

# Verify signatures + SBOM before import
# Import images + chart into customer registry

Validation:

bash scripts/air-gap-audit.sh
MOLAR_AIRGAP_STRICT=1 MOLAR_AIRGAP_BUNDLE=/path/to/bundle bash scripts/air-gap-audit.sh
bash scripts/kind-helm-playwright.sh   # 3-node validation cluster

Zero-egress audit

1. Packet capture before install
2. Install with networkPolicy.denyEgress=true
3. Run Playwright suite + SDK workflows
4. Confirm no DNS/TCP leaves cluster except approved registry import
5. Attach capture summary to acceptance record

Authentication

Clones has two auth domains — do not conflate them:

Human operators (dashboard)

Clones does not ship a separate IdP.

Machines (Molar API API)

MCP / agents

• Hosted: OAuth mcp:clone:write
• Local: org API key or MOLAR_STATIC_TOKEN

The Auth clone (clones-auth) simulates Clerk for your app under test — it is unrelated to Molar operator login.

Upgrade and rollback

1. Take a world snapshot before upgrade
2. helm upgrade with same release name
3. Verify readiness, Playwright examples, audit logs, zero-egress
4. On failure: helm rollback + restore pre-upgrade world snapshot
5. Keep prior image bundle until acceptance signed

See docs/onprem-runbook.md in the repo for the full FinCorp acceptance checklist.

Fleet dashboard

Register BYOC endpoints at app.molar.it/dashboard/clones/fleet:

• Health check interval and labels (env, region)
• Helm release version and pod readiness
• Pre-warmed pool config (idle containers per kind)
• Garage snapshot store capacity
• Webhook signing secret rotation

Security trust domains

Full trust model: docs/security-trust-domains.md in the molar-clones repo.

Related

• Dashboard → Fleet
• Quick start — local spawn
• API & SDK — Molar API endpoints