Creating and configuring pools

Create Pool dialog
The Create Pool wizard — choose pool type, name, repository, and Salesforce connection

Click Create Pool on the Pools page to launch the creation wizard. It walks you through three steps.

Step 1: Basic info

  • Pool type — choose Sandbox (clone from production org) or Scratch Org (create from source branch). This determines how environments are provisioned and what lifecycle they follow.
  • Pool name — a human-readable label (e.g., "Development Pool").
  • Pool tag — a unique identifier used to reference this pool (e.g., development-pool). This is the key that connects everything — monitoring jobs, fetch requests, and configuration all reference the pool by its tag.
  • Repository — the repository this pool is associated with. For scratch org pools, codev clones this repository and installs its packages into each new scratch org.
  • Parent production connection (sandbox pools) — the production user used to provision and manage the sandboxes and authenticate ephemeral review environments. Dev Hub enablement is not required.
  • DevHub connection (scratch org pools) — the Dev Hub user used to create and manage scratch orgs.
  • Source sandbox name (sandbox pools only) — which sandbox to clone from. Leave empty to create fresh sandboxes from production.

Connection permissions

Use a dedicated user for each purpose. The selected username identifies the authenticated user; two users in the same production org remain separate choices.

For sandbox pools, ask your Salesforce administrator to grant Manage Dev Sandboxes for Developer and Developer Pro sandboxes, or Manage Sandboxes for all sandbox types, together with the API access required by your authentication method. A System Administrator profile is not required solely for sandbox management. Confirm available licenses and any source-sandbox access requirements. See Salesforce sandbox permissions.

For scratch pools, the user needs the relevant Dev Hub permissions. Packaging requires its own permissions. Restricted licenses have additional limitations; see Dev Hub connections before choosing a user for automated pools.

Keep a sandbox pool's parent production connection available for its full lifetime, including refresh, deletion, and review-environment authentication. Pool access does not configure or select a production deployment environment.

Step 2: Pool config

This step controls how many environments the pool maintains and how long they live.

  • Min available instances — the floor. codev automatically provisions new environments whenever available count drops below this number. Set this based on how many developers typically need environments at the same time.
  • Max total instances — the ceiling. The pool will never exceed this number, even during replenishment. This protects your org limits.
  • Sandboxes per monitor run (sandbox pools) — the most sandboxes one monitoring cycle requests from Salesforce, from 1 to 20. The default is 5. See Sandboxes per monitor run.
  • Days to keep unassigned — how long an available (but unfetched) environment stays in the pool before being removed. This prevents stale environments from accumulating.
  • Expiration strategy — under When a sandbox expires, what happens to a sandbox once its assignment ends:
    • Delete (the default) — deletes the sandbox in Salesforce, and the pool creates a new one in its place.
    • Refresh — refreshes the sandbox in place from the pool's source and returns it to the pool with the same name. See Refreshing expired sandboxes.
    • Flag Expired and Notify Only are shown but cannot be selected. A pool already set to one of them keeps it when you save.
  • Pool status — toggle the pool active or inactive. Inactive pools stop monitoring and provisioning.

Sandbox pools also have a Branch Sync section on this step; see Branch sync settings.

Refreshing expired sandboxes

Expiration Strategy section of the Pool Config step with Refresh selected
Refresh selected under When a sandbox expires

With Refresh, an expired sandbox is refreshed from the pool's source sandbox, or from production when the pool has no source sandbox. The sandbox keeps its name and its place in the pool. When Salesforce finishes the refresh, codev activates the pool's users as it does for a new sandbox and renews the stored login, and the sandbox is Available again. The Review step shows the choice as When a sandbox expires: Refresh.

On the pool's detail page, such a sandbox is Flagged for refresh while it waits for a refresh, and Refreshing while Salesforce refreshes it. The pool card and the detail page show how many sandboxes are in each status, and the instance list can be filtered by either one. The pool counts these sandboxes toward its available instances, so it does not create replacements for them.

  • Refresh interval. Salesforce allows a refresh only after the sandbox license's refresh interval, counted from when the sandbox was created or last refreshed: 1 day for Developer and Developer Pro, 5 days for Partial Copy, 29 days for Full. A sandbox that expires inside the interval stays Flagged for refresh until the interval has passed, and is then refreshed; hover over its status to see when. It is not deleted meanwhile, so the pool can have fewer sandboxes ready to fetch until then.
  • Per-run limit. Refreshes count toward Sandboxes per monitor run, together with new sandboxes. Refreshes are requested first; the rest wait for the next cycle.
  • Failures. A refresh that Salesforce refuses for any other reason, or that fails or doesn't finish within 48 hours, puts the sandbox in Error with the reason, under Refresh failed. codev does not delete it: check the reason, then delete the sandbox to free its license.
  • Sandboxes left unassigned. An available sandbox kept longer than Days to keep unassigned is still deleted, as in a Delete pool.

Sandboxes per monitor run

Sandboxes per monitor run field under Instance Management on the Pool Config step
The Sandboxes per monitor run field under Instance Management

When a sandbox pool is below its minimum, each monitoring cycle requests at most Sandboxes per monitor run new sandboxes. A larger shortfall is filled over the following cycles, and the cycle's log says how many sandboxes remain and over how many cycles.

The fill rate is this limit times the monitoring cycles per hour. With the default limit of 5 and a cycle every 30 minutes, a pool gains up to 10 sandboxes an hour, so a pool raised from 0 to a minimum of 60 reaches it after about 12 cycles (6 hours). To fill a pool faster, raise the limit, up to 20.

In the pool's YAML configuration the setting is maxProvisionPerRun. Scratch org pools do not have this limit.

Large sandbox requests

Large sandbox request warning on the Review step, with the Confirm and update button
A save that would request more than 10 sandboxes waits for confirmation

Creating or editing a sandbox pool so that it would request more than 10 sandboxes, and more than its current configuration would, needs a confirmation. codev counts the sandboxes from the new minimum and maximum and the sandboxes the pool already has. When you click Create Pool or Update Pool, nothing is saved yet: the Review step shows Large sandbox request, with the number of sandboxes, the parent production connection they are requested from, and about how many monitoring cycles the pool needs to reach its minimum. Click Confirm and create or Confirm and update to save the change, or go back and change the numbers.

Lowering the minimum, a small increase, or an edit that does not change the minimum or maximum saves without the warning.

The CLI asks for the same confirmation. sfp server pool config create and sfp server pool config update stop with a message that names the flag, and save nothing. Run the command again with --confirm largeProvision to apply the change. A pipeline that runs these commands without the flag fails rather than requesting the sandboxes. See sfp server pool.

Step 3: Review

The Summary tab lists the settings. The Advanced tab shows the generated YAML configuration, which you can edit for settings the wizard does not show. Click Create Pool to provision the pool.

Once created, codev begins provisioning environments up to the minimum capacity. A sandbox pool requests at most its Sandboxes per monitor run in each monitoring cycle. For scratch org pools, this involves cloning your repository, installing dependencies, and deploying packages into each new org — all handled automatically. You can track progress on the Monitoring page.

Editing a pool

Click Edit pool on the pool detail page, or Edit in the pool's actions menu on the Pools page. The edit dialog has the same three steps and fields as the creation wizard, filled in with the pool's current configuration. The pool type and pool tag cannot be changed.

On the Review step, the Changes tab lists what will change, and the Advanced tab shows the full YAML configuration. Settings that exist only in the YAML are kept when you save from the form. To edit the YAML directly, click Review in the step list and switch to Advanced. Click Update Pool to save. Changes take effect on the next monitoring cycle.

Config changes

Config changes card on a sandbox pool's detail page
The Config changes card lists who changed the pool configuration and what changed

The detail page of a sandbox pool has a Config changes card. It lists the latest 50 creates and updates of the pool's configuration, newest first. Each entry shows who made the change (the user's email, or the application token), whether the pool was created or updated, when, and each changed field with its old and new value. Hover over the time to see the exact date and time. Saves that change nothing are not listed, and changes made before codev recorded them are not shown.

Branch sync settings

Branch Sync section of the Update Pool Configuration dialog
Branch sync settings on the Pool Config step: the branch, an optional release config, and the schedule

Sandbox pools have a Branch Sync section on the Pool Config step, both when creating and when editing a pool. It sets the branch that codev deploys to the pool's available sandboxes; see Syncing sandboxes with a branch for how a sync runs.

  • Sync branch — the branch to sync to. Without a branch, the pool cannot be synced.
  • Release config — optional. Limits a sync to the packages in this release config. Empty syncs all packages.
  • Scheduled sync — off by default. When on, codev syncs the pool's available sandboxes on the Sync schedule, a five-field cron pattern. The default, 0 */2 * * *, runs every two hours.
  • Sandboxes at a time — how many sandboxes sync at once, from 1 to 20. The default is 5. It applies to Sync all and to the schedule. The server also caps how many sandboxes sync at once across all pools, two unless the server's administrator raised it (see Scaling workers); a sandbox past that cap starts when another sync finishes.

Turning off Scheduled sync, removing the branch, or deleting the pool removes the schedule. Manual syncs stay available while the pool has a branch.

The same settings are stored as syncConfig in the pool's YAML configuration:

Pool Config (YAML)
syncConfig:
  branch: main
  releaseConfigPath: config/release-config-sales.yaml
  enabled: true
  cronPattern: 0 */2 * * *
  batchSize: 5

The YAML also accepts packages, a comma-separated list of packages to sync.

Deleting a pool

Click the delete action on a pool row to remove it. This stops monitoring and provisioning for the pool. Existing instances are cleaned up according to the expiration strategy.

On this page