Configuration
Cartographer is configured through the dashboard (preferred for cloud users) and environment variables (required for self-hosted deployments). This page covers both.
Dashboard settings (recommended)
| Area | Path | What you set |
|---|
| AI & models | /dashboard/ai-settings | Hosted vs BYOK, per-capability model routing |
| Credentials | /dashboard/projects/{id}/credentials | Aliases — secrets never shown after save |
| Project | /dashboard/projects/{id}/settings | Seed URLs, scope, extension allowlist |
See BYOK & models for hosted vs bring-your-own-key routing.
Per-capability model routing
Cartographer uses different models for different stages:
| Capability key | Stage |
|---|
planner | Agent planning |
grounding_tier0 | Accessibility-tree grounding |
grounding_tier1_vlm | Vision escalation + crawl interactive discovery |
export_generator | Playwright code generation |
export_healer | Export self-verify repair loop |
passive_ux_vlm | Sampled UX screenshot analysis |
embeddings | Route map and skill-cache vectors |
stagehand_planner / stagehand_vlm | Stagehand bridge overrides |
Default inference mode: molar (hosted gateway). BYOK integrations add rows per provider (Anthropic, OpenAI, Google, Azure, …).
Core environment variables
API (apps/api)
| Variable | Default | Description |
|---|
CARTOGRAPHER_ENV | local | Deployment profile |
LOG_LEVEL | info | Logging verbosity |
SECRET_KEY | — | Change in production (≥32 chars) |
POSTGRES_URL | local DSN | Application + Hatchet database |
Object storage
| Variable | Default | Description |
|---|
S3_ENDPOINT | http://localhost:9000 | MinIO or AWS S3 endpoint |
S3_ACCESS_KEY_ID | — | Access key |
S3_SECRET_ACCESS_KEY | — | Secret key |
S3_BUCKET_ARTIFACTS | cartographer-artifacts | Screenshots, exports, HAR |
S3_BUCKET_TRACES | molar-traces | Trace blobs |
S3_BUCKET_DEMOS | cartographer-demos | Recorded demonstrations |
S3_FORCE_PATH_STYLE | true | Required for MinIO |
ARTIFACT_RETENTION_DAYS | 90 | Blob TTL |
RUN_RETENTION_DAYS | 90 | Run metadata retention |
LLM providers
| Variable | Description |
|---|
ANTHROPIC_API_KEY | Planner / tier-0 / export generator (if not using hosted only) |
GOOGLE_API_KEY | Tier-1 VLM, export healer, passive UX |
OPENAI_API_KEY | Optional alternate provider |
AZURE_OPENAI_* | Azure OpenAI endpoint, deployment, API version |
LLM_MODEL_PLANNER | Default claude-sonnet-4-5-20251022 |
LLM_MODEL_HEALER | Default gemini-2.5-pro |
LLM_MODEL_VLM_FLASH | Default gemini-2.0-flash |
MOLAR_LLM_BASE_URL | Hosted gateway URL (e.g. http://localhost:14000) |
MOLAR_LLM_SERVICE_KEY | Platform service key for molar-managed integration |
ORG_LLM_SPEND_CAP_CENTS_DEFAULT | Org hosted-LLM cap (0 = unset) |
Browser and grounding
| Variable | Default | Description |
|---|
CLOAKSERVE_HOST | localhost | Stealth browser multiplexer |
CLOAKSERVE_PORT | 9222 | CDP port |
DEFAULT_BROWSER_ADAPTER | cloakbrowser | cloakbrowser | camoufox | extension |
DEFAULT_GROUNDING_TIER | 0 | Default per-run tier |
MAX_GROUNDING_TIER | 1 | Hard cap (set 2 for local MLX) |
GROUNDING_T2_SERVER_URL | — | UI-TARS MLX server when tier 2 enabled |
Hatchet (job queue)
| Variable | Description |
|---|
HATCHET_CLIENT_TOKEN | Worker authentication |
HATCHET_CLIENT_HOST_PORT | localhost:7077 |
AGENT_WORKER_SPLIT_QUEUES | Split interactive vs exploration workers |
AGENT_WORKER_INTERACTIVE_SLOTS | Concurrency |
AGENT_WORKER_EXPLORATION_SLOTS | Concurrency |
Redis and live streams
| Variable | Default | Description |
|---|
REDIS_URL | redis://localhost:6379/0 | Run event pub/sub |
MCP_EVENTSTORE_REDIS_URL | same | MCP task resumption |
MCP server
| Variable | Description |
|---|
MCP_HTTP_BASE_URL | Internal base URL MCP tools use to call REST (default http://localhost:8001 in .env.example — set to http://localhost:8000 locally so tools hit the API) |
MCP_SERVICE_ACCOUNT_TOKEN | Service token for MCP internal calls — not the user's OAuth token |
MCP_AUDIENCE | cartographer-mcp |
MCP_EVENTSTORE_REDIS_URL | Redis backing for MCP task state |
Clients connect to {API_URL}/mcp (e.g. http://localhost:8000/mcp), not a separate port.
Auth (web + API)
| Variable | Description |
|---|
BETTER_AUTH_URL | Auth app URL — standalone: same as web; combined: https://app.molar.it |
BETTER_AUTH_SECRET | Session signing secret |
DATABASE_URL | Auth-core schema (web app) |
AUTH_COOKIE_ENABLED | true when browser calls API with cookies |
BFF_JWT_SECRET | Short-lived internal JWT (Better Auth → FastAPI) |
Credentials vault
| Variable | Description |
|---|
SECRETS_BACKEND | local_file | vault | aws_secrets_manager |
CREDENTIAL_ENCRYPTION_KEY | Fernet key for integration secrets |
VAULT_ADDR / VAULT_TOKEN | HashiCorp Vault |
AWS_SECRETS_PREFIX | Prefix for AWS SM paths |
Extension
| Variable | Description |
|---|
EXTENSION_EXPECTED_ID | chrome-extension://<id> after install |
Enterprise
| Variable | Description |
|---|
LICENSE_REQUIRED | Enforce offline license file |
LICENSE_FILE | Path to signed license |
LICENSE_PUBLIC_KEY | Verify key |
Local Tier 2 grounding (optional)
For air-gapped or privacy-strict vision without cloud APIs:
make grounding-install
make grounding-serve
Set DEFAULT_GROUNDING_TIER=2 and MAX_GROUNDING_TIER=2 in .env.
Crawl defaults (project settings JSON)
| Key | Default | Meaning |
|---|
crawl_depth | 4 | BFS depth |
crawl_max_pages | 500 | Page cap |
interactive_crawl | true | SPA click discovery |
interactive_grounding_tier | 1 | Vision for crawl clicks |
interactive_max_clicks_per_page | — | Sequential retry budget |
robots_override | false | Ignore robots.txt |
Run defaults
| Key | Default | Meaning |
|---|
max_steps | 50 | Agent step budget |
grounding_tier | 0 | Starting tier |
human_preset | default | careful for strict timing sites |
headless | true | false for local debugging |
vlm_budget_cents | — | Per-run vision spend cap |
Trace Debugger budgets
Monthly LLM budget for Debugger chat (cents):
| Plan env var | Default cents |
|---|
TRACE_BUDGET_FREE_CENTS | 500 |
TRACE_BUDGET_STARTER_CENTS | 10000 |
TRACE_BUDGET_TEAM_CENTS | 50000 |
TRACE_BUDGET_BUSINESS_CENTS | 250000 |
CLI configuration
cartog config set api_url https://api.cartographer.example
cartog config set token <pat>
cartog whoami
Config file location is printed by cartog config path.
.env file (local)
Copy .env.example from your Cartographer self-host bundle after make bootstrap. Never commit .env to git.
Minimum for a working dev loop:
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
POSTGRES_URL=postgresql+psycopg://cartographer:cartographer@localhost:5432/cartographer
Provider-agnostic hosted routing can substitute Azure/DeepSeek/Nemotron via MOLAR_LLM_BASE_URL without Anthropic keys — see GA deployment notes in the repo.
| Practice | Configuration |
|---|
| No secrets in logs | Aliases only in API payloads |
| CSRF | Enable cookies + X-CSRF-Token on mutating browser requests |
| Rate limits | API_RATE_LIMIT_*, API_RATE_LIMIT_TENANT_* for hosted multi-tenant |
| Internal callbacks | INTERNAL_SERVICE_TOKEN for worker → API |