Guardrails

Guardrails are checked before any mutation (pause, resume, budget change). If a mutation would violate a guardrail, adduck refuses it and prints the reason. This applies to CLI commands, scheduled actions, and MCP tool calls from AI assistants.

View current guardrails

adduck guardrails

$ adduck guardrails

  Project: my-app

  allowMutations          true
  maxBudgetChangePct      25
  maxDailyBudgetMicros    500000000   ($500.00)
  protectedCampaigns      []

Options

Field	Default	Description
allowMutations	true	Set to `false` to put adduck in read-only mode. No pauses, resumes, or budget changes. Good for CI pipelines that should only report.
maxBudgetChangePct	25	The maximum percentage any single budget change can increase a campaign's daily budget. A campaign at $100/day can't be raised above $125 in one command.
maxDailyBudgetMicros	500000000	The absolute maximum daily budget (in micros) for any single campaign. 1,000,000 micros = $1. So 500,000,000 = $500. adduck won't set a campaign above this number.
protectedCampaigns	[]	Array of campaign IDs that can't be paused, resumed, or have their budgets changed. Pass the platform's native campaign ID string.

Editing guardrails

Edit adduck.json directly under the guardrails key:

{
  "guardrails": {
    "allowMutations": true,
    "maxBudgetChangePct": 15,
    "maxDailyBudgetMicros": 200000000,
    "protectedCampaigns": ["1234567890", "9876543210"]
  }
}

Changes take effect immediately. No restart needed.

Running an audit

adduck audit checks your current configuration and live campaign data against the guardrails:

adduck audit

$ adduck audit

  RULE                    STATUS
  ────────────────────────────────────────────────────
  allowMutations          PASS  mutations are enabled
  maxBudgetChangePct      PASS  limit is 25%
  maxDailyBudgetMicros    PASS  cap is $500.00
  protectedCampaigns      WARN  0 campaigns protected (intentional?)

  all campaigns within budget limits

Read-only mode

Set allowMutations: false to prevent any writes. adduck will report what it would have done but won't touch anything:

adduck pause apple 1234567890

# with allowMutations: false:
Error: mutations are disabled in guardrails (allowMutations: false)

This is useful for CI environments where you want spend visibility without the risk of accidentally changing something.

How guardrails apply to MCP

When an AI assistant calls pause_campaign, set_budget, or any other mutation tool via MCP, the same guardrails apply. The MCP server checks them before executing and returns an error if a rule would be violated. The AI sees the error and should tell the user why it couldn't complete the action.