Request Budgets

Request budgets limit how much S3/R2 request pressure a vault sync policy can spend. They are the first defense against accidental scans, runaway downloads, and surprise provider bills.

Presets

Use presets first, then override individual fields only when needed:

1vh vault sync set <vault> --s3-budget-preset conservative2vh vault sync set <vault> --s3-budget-preset balanced3vh vault sync set <vault> --s3-budget-preset bulk4vh vault sync set <vault> --s3-budget-preset unlimited

Preset	Use for
`conservative`	Unknown buckets, exploratory imports, or first sync tests.
`balanced`	Normal small-to-medium vaults.
`bulk`	Planned high-volume imports or maintenance windows.
`unlimited`	Controlled one-off work where cost is bounded outside Vaulthalla.

Custom Limits

Set specific request budgets:

1vh vault sync set archive \2  --s3-budget-list 100 \3  --s3-budget-head 1000 \4  --s3-budget-get 1000 \5  --s3-budget-put 1000 \6  --s3-budget-copy 100 \7  --s3-budget-delete 1000 \8  --s3-budget-download-bytes 10G

Clear a specific field with values such as unlimited, none, or null:

1vh vault sync set archive --s3-budget-get unlimited

Budget Fields

Field	What it controls
`--s3-budget-list`	Bucket listing and reconcile scan pressure.
`--s3-budget-head`	Remote object metadata checks.
`--s3-budget-get`	Object GET requests and manifest reads.
`--s3-budget-put`	Uploads and manifest publishes.
`--s3-budget-copy`	Provider-side object copy operations.
`--s3-budget-delete`	Remote delete operations.
`--s3-budget-download-bytes`	Body download traffic.

Remote Index Freshness

Set the maximum age of the local remote index:

1vh vault sync set archive --max-remote-index-age 24h

Use unlimited only when another process guarantees the index is correct:

1vh vault sync set archive --max-remote-index-age unlimited

If the index is stale and cannot be refreshed, sync stalls instead of trusting potentially wrong remote state.

Large Bucket Pattern

For large existing buckets:

Create the vault with conservative request budgets.
Import S3 Inventory:

1vh vault sync inventory <vault> --file inventory.csv

Ingest S3 events after the inventory point:

1vh vault sync events <vault> --file s3-events.json

Dry-run:

1vh vault sync dry-run <vault>

Reconcile only in a maintenance window:

1vh vault sync reconcile <vault> --allow-list-scan

Web Console

In the S3/R2 vault form, use the Cost Controls section to choose a request-budget preset or custom limits. The same form also controls sync interval, max remote-index age, sync strategy, conflict policy, and whether sync is enabled.

After saving, verify with:

1vh vault sync info <vault>

Troubleshooting Budget Stalls

If sync stalls:

1vh vault sync info <vault>2vh vault sync dry-run <vault>

Read the stall reason, then raise only the exhausted field. For example, if LIST is exhausted during reconcile, raise --s3-budget-list or switch to inventory/event ingestion instead of making every request type unlimited.