Configure your deployment

Configuration is the deployment-wide set of values an operator controls: credentials, behaviour switches, retention, and outbound network policy. Where an Agent’s instructions, connections, and channel grants are per-Agent state a workspace admin edits in Admin, configuration applies to the whole deployment and mostly arrives as environment variables. This page covers where each value can live, which source wins when two are set, how to change one on each target, and the switches worth knowing.

Where a value can live

Chickpea reads configuration from two places: the deployment’s environment, and its own settings store. Some values accept either.

Everything else on this page is environment only.

The precedence rule

• An environment value beats a stored value. Each setting with both homes checks the environment first and reports its source as env, then falls back to the settings store and reports stored.
• Admin refuses to overwrite an environment value. Saving a provider key that the environment already supplies returns provider_key_read_only; a behaviour switch the environment already sets returns slack_setting_read_only and names the keys. A Composio key from the environment is returned as read only, so Admin can prepare defaults but cannot replace or disable it.
• A blank Worker variable means unset. Chickpea’s environment helper takes the Worker variable or secret whenever one is bound, so a deliberately blank binding is not overridden by a stale process value. It reads as unset.
• Two settings have no environment path at all. Outbound access is stored only, and so are the Slack credentials.

Because the environment wins, moving a value out of the environment and into Admin means removing the variable and restarting, not only saving in the browser.

On Cloudflare

npx wrangler secret put ANTHROPIC_API_KEY

A button deploy asks for no keys. .dev.vars.example contains only comments because the Deploy to Cloudflare button renders every active key in that file as a required prompt, and provider keys must stay optional. wrangler.jsonc carries no vars block for the same reason: non-secret defaults live in product code rather than as customer-editable deploy fields.

Redeploy with the wrapper. Use npm run deploy, or npm run deploy:sandbox for the coding sandbox. Bare wrangler deploy skips the artifact check, the preserved AUTH_DB identity and credential roots, the reviewed migrations, and the readiness check.

On Node

The built server reads runtime environment variables. It does not load your development .env file, so production values belong in a protected environment file the supervisor passes in.

TAG_RUN_BODY_RETENTION_DAYS=30
CHICKPEA_TELEMETRY_ENVIRONMENT=production

sudo systemctl restart <your-chickpea-unit>

Verify

• Check a provider key’s source. In Settings → Model providers, a key supplied by the environment reads Environment managed; one saved in the browser reads Saved in Chickpea.
• Check a Slack behaviour switch. GET /admin/api/slack-behavior returns each switch as a value plus a source of env, stored, or default.
• Check outbound access. GET /admin/api/egress returns the stored policy.

Slack behaviour switches

Four switches are on by default and turn off only for an explicit false spelling: false, 0, off, or no, in any case. Any other value, including an unset one, leaves the behaviour on.

The first two also have stored twins, slack.behavior.unassignedHint and slack.behavior.welcomeOnJoin. Chickpea resolves them in this order: an environment value, then the stored value, then the default of on. While the environment sets one, a write to it returns slack_setting_read_only and names that key. The twins have no control in the Admin browser app; they are read and written through GET and PUT /admin/api/slack-behavior with a body of {"unassignedHint": false} or {"welcomeOnJoin": false}.

The last two switches are deployment only. They have no stored twin and no Admin control, and SLACK_TAG_SEMANTIC_ACTIVITY_STATUS is not listed in .env.example.

The Slack credential exception

.env.example and the README’s configuration table say an environment value takes precedence for SLACK_SIGNING_SECRET and SLACK_BOT_TOKEN. The running deployment does not do that. Slack credential resolution is backed by one complete encrypted credential revision, and no runtime source reads those two variables or SLACK_BOT_USER_ID; only development and test scripts do. A regression test sets all three to conflicting values and asserts the stored revision still wins.

So changing Slack credentials means running Chickpea’s Slack connection flow again, which writes a new encrypted revision. Setting the variables changes nothing, and Admin reports each credential’s source as stored or missing, never env. Treat the two lines in .env.example and the README as stale.

Outbound access

Outbound access is the policy that governs the internet access available to the coding sandbox’s curl. MCP connectors are separate and always work, and private and internal addresses are always blocked. Change it in Settings → Outbound access.

The policy is stored under the egress.policy setting. There is no environment variable for it, and an unparseable or malformed stored value falls back to the default allowlist rather than opening access.

Telemetry and usage

Anonymous, content-free product telemetry is on by default and has a complete opt-out.

Opting out of telemetry is total: the composition returns a no-op before reading or creating identity state, reading inventory, generating randomness, starting a timer, or making a network request. Nothing is buffered for later delivery. An unsupported CHICKPEA_TELEMETRY_ENVIRONMENT value is labelled development rather than entering the production measurement set; when the variable is unset, a NODE_ENV of production, development, or test is used before the target default.

The three usage layers are independent, and only 1 and true keep one on. Any other value switches that layer off, so use 0. CHICKPEA_INSTALLATION_ID must match ^[A-Za-z0-9][A-Za-z0-9:._/@-]{0,255}$; anything else falls back to chickpea.

Retention

TAG_RUN_BODY_RETENTION_DAYS sets the retention recorded when a canonical run body is written. It takes an integer from 1 through 365 and defaults to 30. A non-integer or out-of-range value fails with TAG_RUN_BODY_RETENTION_DAYS must be an integer from 1 to 365.

Changing the value does not rewrite existing expiries; it applies to bodies written after the change. A Chickpea purge does not delete Flue transcripts, which follow the transcript database at TAG_DB_PATH on Node.

Advanced switches

Two switches exist for incident response and staged rollout. Neither changes work that has already been admitted, and neither tells you anything about the state of the other.

• CHICKPEA_LIVE_CHANNEL_CONFIG is on by default, so channel events resolve current Agent and channel configuration. Setting 0, false, or off restores write-once thread snapshots for new channel admissions. It is an emergency rollback; unset it and redeploy once the incident is understood.
• SLACK_TAG_LEDGER_CANARY_CHANNELS is empty by default and takes at most 20 comma-separated workspace/channel pairs, such as T123/C456. Agents with connections or repositories, and deployments whose outbound access is open or a non-empty allowlist, stay on the established lane regardless. Read docs/runbooks/agent-runtime-rollout.md in the product repository before setting it.

Next steps

• Deploy and operate: the Cloudflare and Node procedures these values apply to.
• Environment variables: the complete variable list, with when each is required and what it defaults to.
• Security model: what the outbound access policy and credential handling actually guarantee.
• A tour of Admin: the browser app where stored settings live.