A feature needs a credential before it can fully work, such as a payment secret key or API token.
Runtime Secrets
Runtime Secrets are the private values your Project needs while it is running: API keys, access tokens, webhook secrets, and other credentials used to call external services.
Use Runtime Secrets when a Project needs something outside Castaly, such as a payments provider, email service, AI model, analytics tool, or third-party API. Castaly stores these values separately from Chat, the Spec, and code so they can be used at runtime without being exposed in the Project definition.
When Castaly asks for a secret
Section titled “When Castaly asks for a secret”Castaly creates Runtime Secret rows when a Build or Project capability needs a value at runtime.
Castaly lists only the secrets the Project needs. If none are required, Runtime Secrets shows No secrets required.
Secrets belong to the current Project. They are not global account settings.
What secrets affect
Section titled “What secrets affect”A missing required secret affects runtime behavior and Publish readiness. It does not stop Castaly from understanding or building your Project.
| Area | What happens when a required secret is missing |
|---|---|
| Build | Build can still run. |
| Preview | Preview can still open, but the feature that needs the secret may not work. |
| Publish | Publish is blocked until the required secret is configured. |
When Publish is blocked by a missing required secret, the Project shows Configuration required.
Required vs optional secrets
Section titled “Required vs optional secrets”Runtime Secrets can be required or optional.
- Required secrets must be configured before you can publish.
- Optional secrets support additional behavior, but may not block Publish.
- The UI is the source of truth for whether a missing secret blocks the current Project.
Open Runtime Secrets
Section titled “Open Runtime Secrets”You can open Runtime Secrets in two ways:
From Project Settings
In the Project Workspace top bar, open the gear icon, then choose Runtime Secrets.
Path: Project Workspace → gear icon → Runtime Secrets.
From Configuration required
If the Project shows Configuration required, click Set up to jump directly to Runtime Secrets.
Path: Configuration required → Set up → Runtime Secrets.
Add or replace a secret
Section titled “Add or replace a secret”Open a Missing secret
Find the row with status Missing, then choose Set secret.
Enter the value
Paste the API key, token, or secret value into the input.
Save
After saving, the status changes to Configured.
Replace when needed
To rotate a credential, choose Edit secret and save a new value. Editing replaces the stored value; it does not reveal the old one.
Read the table
Section titled “Read the table”Runtime Secrets is a table. Castaly fills in the rows your build actually needs, grouped as Required or Optional.
| Column | What it shows |
|---|---|
| Name | The secret’s key, e.g. STRIPE_SECRET_KEY |
| Environment | Where it applies — Preview or Production |
| Value | Not set before configuration, masked after saving |
| Status | Missing, Configured, or Dismissed |
| Action | Set secret, Edit secret, or Read-only |
Missing secrets and Publish
Section titled “Missing secrets and Publish”A missing required secret does not stop you from building or previewing.
Build and Preview keep working
You can run a Build and get a working Preview even with a required secret still Missing. The feature that needs it may not work yet, but nothing is blocked.
The Project shows Configuration required
Castaly marks the Project Configuration required and offers a Set up shortcut into Runtime Secrets.
Publish is blocked until it's filled
You can’t Publish a Project Version while a required secret is Missing. Fill it in, and Publish unblocks.
This is the one Project Settings rule that gates Publish. See Blockers for the full picture of what can hold a Project back.
Security notes
Section titled “Security notes”Runtime Secrets are sensitive credentials. Treat them like production keys.
Saved secrets are encrypted while stored.
After saving, Castaly only shows a masked value. To change it, replace it.
Do not paste secrets into Chat, the Spec, public docs, or visible page content.
While you are editing a secret, the input shows what you are typing so you can confirm it before saving. After it is saved, the stored value stays hidden.
Next: when required secrets are configured, continue to Publish Your Project or set your published URL in Project URLs.