Configuration

Updated

Capstan is configured through environment variables on its Laravel Cloud environment. Everything here has a working default, so none of it is needed for Capstan to run.

Where to change a setting

The optional settings Capstan declares appear on the full deploy screen in Scalpels when you install, where you can set them before the first deploy. After the install, change them in the environment's variables in the Laravel Cloud dashboard and redeploy. Capstan reads its configuration when it boots, so a change takes effect on the next deploy.

Leave these alone

Anything Laravel Cloud wrote for a resource. When Cloud attaches the database, queue and bucket, it writes their settings, including connection names such as DB_CONNECTION, QUEUE_CONNECTION, CACHE_STORE, FILESYSTEM_DISK and the AWS_* keys. If you set one yourself, your value replaces Cloud's and the resource stops working, while the deploy stays green.
APP_KEY. Generated for the environment. Changing it invalidates every encrypted value and signs everyone out.
SESSION_DOMAIN. Leave it unset. If the app and artifact hostnames share a parent domain, a shared session domain hands your login cookie to the artifact hostname and removes the isolation artifact hosting depends on.
The application timezone. Capstan ships with UTC and refuses to boot with Postmaster on under any other timezone, because message signatures are computed over UTC timestamps.

The capability switches

Variable	Default	What it does
`CAPSTAN_FEATURE_ARTIFACTS`	Scalpels-enabled	Records the intent to use artifact hosting. Scalpels sets it to `true` during installation; Capstan still keeps artifacts unavailable until the app and render origins differ. Do not set it yourself.
`CAPSTAN_FEATURE_POSTMASTER`	`false`	Turns Postmaster on. While it is off, the Postmaster page, the poll API and the Postmaster MCP tools refuse, and the Postmaster link is not in the sidebar.

Artifact settings

Variable	Default	What it does
`CAPSTAN_ARTIFACT_RENDER_ORIGIN`	Scalpels-managed	The environment's `laravel.cloud` address, used as the isolated artifact hostname after you add a custom app domain. It is derived automatically and does not appear on the install form. Do not set it yourself.
`CAPSTAN_ARTIFACT_MAX_CONTENT_BYTES`	`1048576`	The largest artifact accepted, in bytes (1 MB). A bigger one is rejected with `422`.

Capstan also reads four allowlists, CAPSTAN_ARTIFACT_CSP_SCRIPT_SRC, _STYLE_SRC, _FONT_SRC and _IMG_SRC. Each is a comma-separated list of extra sources artifact HTML may load scripts, stylesheets, fonts or images from. All four are empty by default, which means an artifact can load nothing from the network. They are not offered on the Scalpels install screen on purpose: loosening the policy is a security decision to make with a specific artifact in front of you. See Artifact hosting for what the policy allows.

Postmaster settings

Variable	Default	What it does
`CAPSTAN_SERVER_ID`	none	This server's permanent Postmaster address. Leave it blank: Capstan mints one the first time it needs it and stores it in the database. Set it only to restore a previous identity after rebuilding a server.
`CAPSTAN_POSTMASTER_MAX_INBOUND`	`50`	The most messages one poll returns. The rest stay queued for the next poll, in order.

Capstan also reads four timing settings: CAPSTAN_POSTMASTER_MAP_STALE_AFTER_SECONDS (300), CAPSTAN_POSTMASTER_PROBE_INTERVAL_SECONDS (300), CAPSTAN_POSTMASTER_PROBE_TIMEOUT_SECONDS (900) and CAPSTAN_POSTMASTER_PROBE_BACKOFF_SECONDS (1800). They are tuned against each other and against the once-a-minute poll and sweep, so moving one on its own gives you a map that reports healthy agents as offline or a probe that hammers a dead one. Scalpels does not offer them, and you should leave them at their defaults. Postmaster explains what each one governs.

Other settings

Variable	Default	What it does
`BUILT_FOR_CLOUD_PRODUCT`	`Capstan`	The product name reported by the public `GET /bfc/meta` endpoint.
`CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_EMAIL_TOKEN`	none	Credentials for sending invitation email through Cloudflare Email Sending. They only take effect when the deployment's mailer is set to Cloudflare and its sender address is on a Cloudflare-verified domain.