Skip to content
Agentful

Configuration

This page lists the configuration operators usually touch. Keep secrets in the host environment or secret manager, not in the repo.

Core

Section titled “Core”
Variable Purpose
DATABASE_URL Postgres connection string
WEB_ORIGIN Public storefront origin, used for redirects and CORS
JWT_SECRET Auth token signing secret
API_PREFIX API prefix, defaults to /api in the app shape
PORT API listen port

MCP

Section titled “MCP”
Variable Purpose
MCP_ALLOWED_ORIGINS Comma-separated browser origins allowed to call MCP

Mail

Section titled “Mail”
Variable Purpose
SMTP_URL SMTP transport URL
MAIL_FROM From address for transactional mail

Product Images

Section titled “Product Images”
Variable Purpose
S3_BUCKET Product image bucket
S3_REGION Region for the S3-compatible provider
S3_ENDPOINT Optional custom S3-compatible endpoint
S3_FORCE_PATH_STYLE Optional path-style mode for MinIO-like providers
S3_PUBLIC_BASE_URL Public image base URL
PRODUCT_IMAGE_UPLOAD_TTL_SECONDS Signed upload URL lifetime
AWS_ACCESS_KEY_ID S3 credential
AWS_SECRET_ACCESS_KEY S3 credential

The bucket or CDN must allow public GET/HEAD for product image URLs. Browser uploads need CORS permission for PUT with Content-Type.

Payments

Section titled “Payments”

Local development defaults to PAYMENT_PROVIDER=dev. Production should use Stripe:

Variable Purpose
PAYMENT_PROVIDER=stripe Enables Stripe Checkout flow
STRIPE_SECRET_KEY Stripe secret key
STRIPE_WEBHOOK_SECRET Stripe webhook signature secret
STRIPE_CURRENCY Optional, defaults to usd

Configure Stripe webhooks to call:

POST /api/payments/stripe/webhook

Agentful Cloud

Section titled “Agentful Cloud”

These are only required for the managed cloud control plane.

Variable Purpose
CLOUD_CELLS_JSON JSON array of regional cell metadata; see deploy/cloud-cells.example.json
CLOUDFLARE_API_TOKEN Cloudflare API token used to create proxied shop DNS records
CLOUD_CELL_*_POSTGRES_ADMIN_URL Per-cell admin Postgres URL referenced by each cell’s postgresAdminUrlEnvVar
CLOUD_SHOP_MIGRATE_SCRIPT Optional migration script path, defaults to tools/release/migrate.mjs

Keep Cloudflare, Cloudzy, and database credentials in the host environment or secret manager. For local operator shells, load them through 1Password CLI with op read; do not commit resolved token values.