Deployment

Cartographer supports three deployment patterns:

The application behavior is the same across modes — only topology, auth issuer URL, and who operates workers/storage changes.

Molar Cloud (managed)

Best for: teams that want crawls, runs, and exports without running Docker.

1. Sign up at app.molar.it
2. Ensure your org has the Cartographer entitlement (standalone or bundle)
3. Open app.molar.it/dashboard/cartographer
4. Connect MCP via OAuth from Integrations → MCP

Infrastructure (operated by Molar):

• Molar API + Better Auth (combined mode)
• Cartographer API, workers (crawl, agent, export, trace)
• Postgres (Supabase), Redis (Upstash), object storage
• LiteLLM gateway for hosted models
• MCP endpoint: https://mcp.molar.cloud

Your responsibilities:

• Target app URLs and credentials
• BYOK keys (optional)
• GitHub App install for export PRs

Product marketing and deep links: cartographer.molar.it

Local development

Best for: contributing, debugging, or evaluating before purchase.

# From your Cartographer self-host bundle (contact support@molar.it for access)
make bootstrap
make dev
make seed

Services and ports

Start workers in separate terminals:

make agent-worker
make crawl-worker
make export-worker

Customer docs are always at docs.molar.it.

Docker Compose (self-hosted)

Best for: single-node production, pilots, or air-gapped connected deployments.

The Cartographer self-host bundle includes Docker Compose definitions used by make dev. Production self-hosters typically:

1. Pin image tags and CloakBrowser binary checksums (never set CLOAKBROWSER_SKIP_CHECKSUM=true)
2. Point POSTGRES_URL, REDIS_URL, and S3_* at managed services or HA clusters
3. Set SECRET_KEY, BETTER_AUTH_SECRET, CREDENTIAL_ENCRYPTION_KEY, JWT keys from a secrets manager
4. Scale worker containers horizontally; Hatchet coordinates concurrency
5. Terminate TLS at your ingress; set AUTH_COOKIE_SECURE=true

Minimum production topology

                    ┌─────────────┐
  Users ───────────►│  Ingress    │
                    │  (TLS)      │
                    └──────┬──────┘
           ┌───────────────┴───────────────┐
           ▼                               ▼
      ┌─────────┐                   ┌───────────┐
      │ Web UI  │                   │ API :8000 │
      │ :3000   │                   │ REST + MCP│
      └─────────┘                   │ /mcp      │
                                    └─────┬─────┘
                          │
              ┌───────────┼───────────┐
              ▼           ▼           ▼
        ┌──────────┐ ┌─────────┐ ┌─────────┐
        │ Hatchet  │ │ Workers │ │cloakserve│
        └──────────┘ └─────────┘ └─────────┘
              │           │
              ▼           ▼
        ┌─────────────────────────┐
        │ Postgres + Redis + S3   │
        └─────────────────────────┘

Worker types

Standalone vs combined auth

Both modes use Better Auth and the shared @molar/auth-core schema — not two different login stacks.

FastAPI remains authoritative for projects, runs, credentials, exports, and extension tokens. Browser signup flows through Better Auth; the API validates session via dashboard API JWT or shared session lookup.

For enterprise auth topology (standalone SKU vs combined bundle), contact support@molar.it.

On-prem / air-gapped

Best for: regulated industries, no outbound screenshot policy, or contractual data residency.

Tier 2 grounding install:

make grounding-install
make grounding-serve

Helm charts for enterprise SKUs are available from Molar support. Contact support@molar.it for packaging and cluster install guidance.

E2B / code sandbox (export verify)

Export self-verify runs generated tests in an isolated sandbox (E2B Firecracker in production, microsandbox on Apple Silicon dev). Ensure workers can reach the sandbox API and that egress policies allow only your target app origins.

Observability

Correlate by trace_id across Langfuse and Jaeger.

Upgrades and migrations

• Database schema: Alembic migrations only — run make migrate after pulling new versions
• CloakBrowser: binary updates via make bootstrap with checksum verification
• Zero-downtime: roll API first, then workers (workers tolerate brief API version skew)

Deployment checklist

• Postgres backups and org_id RLS verified
• S3 bucket policies scoped per org prefix
• LLM keys or hosted gateway configured
• All four workers healthy in Hatchet
• cloakserve reachable from agent-worker
• TLS and BETTER_AUTH_SECRET rotated from dev defaults
• Credential vault backend production-ready (not local_file)
• Rate limits enabled for multi-tenant hosted (API_RATE_LIMIT_TENANT_*)

Related

• Quick start — bootstrap commands
• Configuration — full env var list
• Dashboard — entitlements and usage on cloud