> ## Documentation Index > Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt > Use this file to discover all available pages before exploring further. # Collection Environment Defaults > Define expected environments, base URLs, and default clients at the collection level. New routes auto-provision, existing routes stay in sync, and drift is visible at a glance. # Collection Environment Defaults When all the routes in a collection share the same shape — the same environments, the same target host pattern, the same set of clients — it's tedious (and error-prone) to configure each route individually. **Collection environment defaults** let you declare what a collection *expects* once, and every route in the collection automatically picks it up. ## What You Can Define For each collection, you configure: | Setting | Scope | Description | | ------------------------- | --------------- | ------------------------------------------------------------------------------------------------- | | **Expected environments** | Collection | The list of environments routes in this collection should have (e.g. `production`, `development`) | | **Base URL** | Per environment | The default target host used when prefilling new routes | | **Default clients** | Per environment | Clients automatically attached to routes in that environment | | **Header injections** | Per environment | *(Reserved for future use)* | | **Body injections** | Per environment | *(Reserved for future use)* | Expected environments is a **list**, not a single value. A Shopify collection might expect both `production` and `development`, so every route in it is guaranteed to have both configured. *** ## Why Use Collection Defaults? ### Without Defaults Every time you add a route to a collection, you have to remember to: 1. Create a `production` environment config 2. Create a `development` environment config 3. Paste the same base URL everywhere 4. Attach the same four or five clients on both environments 5. Hope nobody forgets a step three weeks from now ### With Defaults * **Declare once** — "This collection has production and development, base URLs are X and Y, and these clients are always attached." * **Auto-provision on join** — When a route joins the collection, missing environments are created silently from the defaults. * **Prefill on create** — The route creation form fills in the base URL from the collection. * **Drift detection** — Routes that drift from the defaults are flagged on both the collection page (sync stats) and the route page (clients compare row). * **One-click reset** — Bring a route back to the canonical client list with a single click. *** ## Setting Up Defaults ### 1. Open the Collection's Environments Tab Navigate to **Collections → *your collection* → Environments** tab. ### 2. Declare Expected Environments At the top of the tab, click any environment chip to add or remove it from the expected list. ```text theme={"dark"} Expected environments: [✓ production] [✓ development] [ staging ] ``` Removing an environment from the expected list only stops auto-provisioning going forward. Existing route environment configs are **preserved**, not deleted. If any routes already use that environment, you'll be warned before the change is applied. ### 3. Configure Each Environment Pick an environment from the dropdown and fill in: * **Base URL** — e.g. `https://api.shopify.com` for production, `https://sandbox.shopify.com` for development * **Default clients** — Add the clients that should automatically be attached to every route in this collection+environment ### 4. Save Unsaved changes are shown in a sticky save bar at the bottom of the tab. Click **Save** to persist. Saving only updates the collection's defaults — it does **not** automatically apply them to existing routes. Use **Apply to routes** to push changes out. *** ## Auto-Provision on Join When a route joins a collection (either at creation time or by changing its collection later), KnoxCall silently creates any missing environment configs from the collection defaults. ```text theme={"dark"} Route joins "Shopify APIs" collection └─ Collection expects: [production, development] └─ Route currently has: [production] Result: development is auto-created with: • Base URL from collection • Default clients from collection • inject_headers / inject_body from collection (when configured) ``` This happens silently — no modal, no confirmation. Routes always have every environment the collection expects. Auto-provisioning respects tenant boundaries: environments that don't exist for your tenant are skipped. *** ## Base URL Prefill on Route Creation When creating a new route, selecting a collection triggers a preview panel showing the environments that will be provisioned. At the same time, the target URL input is prefilled with the first expected environment's base URL. A small hint appears below the input: > *Prefilled from collection (production) — click to edit* As soon as you start typing, the prefill is locked out — KnoxCall will never overwrite a value you've explicitly edited. *** ## Keeping Routes in Sync Defaults change over time. When they do, KnoxCall helps you bring existing routes back in line. ### The Sync Stats Row On the collection's Environments tab, below the default-clients editor, a sync row shows: ```text theme={"dark"} 12 routes • 8 synced • 3 out of sync • 1 missing env [ Apply to routes ] ``` * **Synced** — The route's client list matches the defaults exactly. * **Out of sync** — The route is missing some defaults, has extra clients, or both. * **Missing env** — The route has no config for this environment yet. ### Apply to Routes Modal Clicking **Apply to routes** opens a modal that shows every route in the collection with its individual diff: * **+ ClientName (will be added)** — Missing defaults that will be attached. * **− ClientName (will be removed)** — Extras that will be detached *(replace mode only)*. * **(keeping: ClientName)** — Extras that will be preserved *(merge mode)*. You choose the **apply mode**: Add missing defaults, preserve any extra clients already on the route. Safe for routes that legitimately have extra clients. Hard sync: add defaults, remove anything not in the defaults. Use when the defaults must be authoritative. Routes that are out-of-sync or missing-env are **preselected** by default, so one click catches you up on everything. *** ## The Route-Level Compare Row Open any route in a collection that has defaults. On the **Clients** tab, the client compare widget adds a **`{collection} default`** row (for example, `Shopify APIs default`) showing the canonical client list for the current environment. When the route's clients differ from — or are missing — those defaults, the row exposes a single **Apply** action. ### Out of Sync The compare row shows the collection's desired client list alongside the route's current one. The Apply action is titled: ```text theme={"dark"} Reset production to Shopify APIs defaults ``` Triggering it performs a **hard replace** — extra clients are removed, defaults are added exactly. This is the intentional, explicit way to snap a single route back to canonical. ### Missing Env When the route has no config for an environment the collection expects, the compare row's Apply action is titled instead: ```text theme={"dark"} Provision development from Shopify APIs defaults ``` Triggering it creates the environment config for this route using the collection's base URL and default clients. The compare row is part of the clients comparison widget — there's no separate banner to dismiss. It simply reflects the current diff and disappears once the route is in sync. *** ## Merge vs Replace: When to Use Each | Situation | Use | Why | | --------------------------------------------------------------------- | ----------------------- | ------------------------------------------ | | Routine sync after adding a default client | **Merge (bulk)** | Safe — won't clobber route-specific extras | | Onboarding a fleet of existing routes into a collection | **Merge (bulk)** | Adds missing defaults without surprises | | A single route has drifted and you want it back to canonical | **Reset (compare row)** | Explicit per-route hard sync | | The collection is the single source of truth and extras are forbidden | **Replace (bulk)** | Enforces exact defaults on every route | *** ## Real-World Example **Scenario:** An e-commerce team has a "Shopify APIs" collection with 8 routes. They always run routes in both `production` and `development`, and every route needs the `monitoring-probe`, `office-vpn`, and `ci-runner` clients. ### Step 1: Configure the collection once ```text theme={"dark"} Collection: Shopify APIs Expected environments: [production, development] Production: Base URL: https://api.shopify.com Default clients: monitoring-probe, office-vpn, ci-runner Development: Base URL: https://sandbox.shopify.com Default clients: monitoring-probe, office-vpn, ci-runner, dev-laptop ``` ### Step 2: Add a new route The developer creates `shopify-orders` and picks the Shopify APIs collection. KnoxCall: 1. Shows a preview: *"will pre-configure 2 environments"* 2. Prefills the target URL with `https://api.shopify.com` 3. On save, auto-provisions the `development` environment with its base URL and 4 default clients No manual client-attachment, no copy-paste of URLs. ### Step 3: Add a new default client Three months later, the team adds `newrelic-probe` to the collection defaults and clicks **Apply to routes** with **Merge** mode. All 8 routes receive `newrelic-probe` on both environments — without disturbing any route-specific extras. ### Step 4: A stray route A single route `shopify-legacy-sync` was modified by hand and has `legacy-jenkins` attached. Opening its clients tab shows the compare row out of sync with the `Shopify APIs default` — `newrelic-probe` will be added. The developer triggers the **Reset production to Shopify APIs defaults** action. `legacy-jenkins` is removed, `newrelic-probe` is added, and the route matches canonical. *** ## How It Differs from Collection Variables & Inheritance KnoxCall collections have two related — but separate — systems: | Feature | What It Does | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Collection variables** | Resolves `{{var:name}}` template placeholders in route configs at proxy time | | **`inherit_collection_config` / `inherit_collection_auth`** | At proxy time, pulls the collection's base URL or auth config if the route doesn't set its own | | **Collection environment defaults** *(this page)* | Stamps values onto the route itself when it joins the collection or when you click Apply — the route then owns the values | In other words: * **Inheritance** is a proxy-time lookup — change the collection, every route changes instantly. * **Defaults** are a create-time / apply-time stamp — routes own their values, but can be brought back in sync on demand. Use inheritance for values that should be *always* the collection's; use defaults for values that are *typically* the collection's but routes may legitimately override. *** ## Audit Trail Every defaults operation is logged to **Audit Logs**: | Action | When | | ------------------------------------------------ | ---------------------------------------------------- | | `collection_defaults.apply` | Bulk apply with merge or replace | | `route_environment.reset_to_collection_defaults` | Per-route reset via the compare row Apply action | | `route_environment.provisioned_from_collection` | Per-route provision via the compare row Apply action | | `route_environment.auto_provisioned` | Automatic provision when a route joined a collection | Each entry records the collection, environment, route(s) affected, and the mode used. *** ## Best Practices ### ✅ Do * **Declare expected environments early.** Set them before adding routes so auto-provisioning catches everything. * **Prefer Merge over Replace for bulk apply.** Merge is the safe default; Replace should be a deliberate choice. * **Use Reset (per-route compare row) for drift fixes.** It's unambiguous and audit-logged per route. * **Review the Apply modal's diff before confirming.** The preselection helps, but eyeballing it catches surprises. ### ❌ Don't * **Don't use Replace to "clean up" routes you don't fully understand.** Extras may be there for a reason. * **Don't remove an expected environment to hide drift.** The warning flow lets you remove it, but the underlying route configs stay — the drift just becomes invisible. * **Don't rely on defaults for proxy-time behavior.** Defaults stamp values at create/apply time. For proxy-time dynamic lookup, use `inherit_collection_config`. *** ## Quick Reference | Action | Where | Behavior | | ------------------------------ | ----------------------------------------------------- | ------------------------------ | | Declare expected envs | Collection → Environments tab → chip row | Auto-provisions on route join | | Set base URL + default clients | Collection → Environments tab → per-env editor | Saved to the collection only | | Prefill route target URL | Route create page (after picking collection) | Locked out once you type | | Bulk apply to routes | Collection → Environments tab → Apply to routes | Merge or Replace, multi-select | | Single-route reset | Route → Clients tab → compare row Apply | Hard replace | | Single-route provision | Route → Clients tab → compare row Apply (missing env) | Creates env from defaults | *** ## Next Steps Understand the underlying environment system Learn how clients attach to route environments Advanced patterns across environments Review every defaults operation *** **Key Takeaway**: Declare a collection's expected environments, base URLs, and default clients once. New routes auto-provision, existing routes stay in sync via Apply or per-route Reset, and drift never hides for long.