Fetching and Using Environments

Once a pool is provisioned and has available instances, your team can start using them.

Fetching an environment

Click Fetch Sandbox from the Pools page or from the DEV ENVIRONMENTS panel on the right. The dialog shows all pools with their current availability — how many environments are ready and the total capacity.

Select a pool and set the Expiration Hours — this is how long the environment will be assigned to you before it expires and returns to the pool. Click Fetch Sandbox to grab it.

Once fetched, you receive a password reset email from Salesforce to set up your credentials. The environment is immediately assigned to you.

You can see all environments assigned to you under Dev > My Orgs > Assigned to Me in the sidebar.

Fetch hands out an Available sandbox whenever the pool has one. If every free sandbox is being synced to the pool's branch, fetch hands out the sandbox whose sync started first and cancels that sync. codev shows the warning This sandbox may be partly synced, because metadata the sync had already deployed stays in the org. Sync the sandbox from My assignments if you need it to match the branch. See Syncing sandboxes with a branch.

Managing pool instances

Click any pool name on the Pools page to see all its instances. Each instance shows:

• Its current status — Available, Assigned, Syncing, Provisioning, or Expired
• Who it is assigned to (if anyone)
• When it expires, with a countdown (e.g., "2d left", "1h left")
• Action buttons to open, extend, or delete it

Switch to the Pool Config (YAML) tab to view or edit the pool's configuration.

Syncing sandboxes with a branch

A pooled sandbox holds the metadata its source org had when the pool created it. Changes merged to the repository after that point are not in it. Branch sync deploys the packages that changed on a branch to the pool's available sandboxes, so a developer who fetches one starts from the current branch rather than from the day the sandbox was created.

A sync compares the packages installed in the sandbox with the branch and deploys the packages that differ. They are deployed as source, and no Apex tests run. A Release config set on the pool limits the sync to the packages in that release config.

Branch sync applies to sandbox pools. Set the branch in the pool's configuration (see Branch sync settings); without a branch, the sync actions are disabled. The Branch sync card on the pool detail page shows the branch and the schedule, for example Syncs to main · every 2h, 5 at a time.

Running a sync

Pool owners see two sync actions on the pool detail page:

• Sync on an instance row syncs that sandbox. The action is enabled only for an Available sandbox.
• Sync all in the page header syncs every available sandbox in the pool, a few at a time. The pool's Sandboxes at a time setting sets how many sync at once; the next sandbox starts as soon as one finishes.

When the pool has Scheduled sync turned on, codev also runs Sync all on the pool's schedule. The schedule is listed with the pool's jobs on the Monitoring page, where it can be paused and resumed. A scheduled sync leaves out sandboxes that expire within the next three hours, and it syncs the sandboxes whose last sync is oldest first.

While a sandbox syncs

A sandbox that is being synced shows the Syncing status. It is held back from fetch and from review environments while another sandbox is available. When the sync ends, whether it succeeds or fails, the sandbox returns to Available; a sync cancelled by a fetch leaves the sandbox Assigned to the person who fetched it. A failed sync never marks the sandbox as an error and does not change its expiry.

A sync stops after three hours. If a sync ends without reporting back, the sandbox is treated as Available once those three hours have passed.

Assigned sandboxes are never synced from the pool. The person a sandbox is assigned to syncs it from My assignments on the Pools page in the codev web app, so a pool sync never deploys over their work.

Last sync

The icon next to an instance's status shows the result of its last sync: Synced, Sync failed, Sync cancelled, or Sync timed out. Hover over it to see when the sync ran, the branch and commit, and who started it. For a failed sync, it also shows the end of the error output and a View run link to the full run.

Where instances come from

The pool detail page shows a Provisioned from card — the base each instance in the pool is built on. What it shows depends on the pool type:

The base is read-only here — a scratch org's snapshot lives in its scratch definition file in the repository, and a sandbox's source is set in the pool configuration. The Salesforce id is looked up live and shown alongside the name when the base exists; the name is shown on its own when it does not. To change the base, edit the pool's definition (see Creating and configuring pools).

Adding users to an environment

An environment assigned to you starts with your user only. The Add users action on the environment card under Dev > My Orgs > Assigned to Me creates further users in it.

Search for a teammate by name or type an email address. Each row carries its own access level — the profile and permissions the user is created with — and a Reset email toggle that sends the Salesforce password-reset email. Apply to all sets both across every row. A run takes up to ten people.

The access levels come from the project's developer config; with none stored, the dialog blocks submission and links to the page where an owner creates one. Users are created in the org one at a time, so a run can partially succeed — a profile with no license left, for example. codev reports which addresses failed and why, and keeps the users it created.

Extending an environment

If you need more time with an assigned environment, click the extend action on the instance row. The dialog shows the current expiry date and lets you add days. The new expiry is previewed before you confirm.

This is useful when a feature takes longer than expected or when you need to keep an environment around for a demo or review.

Returning an environment

When your lease expires, the environment is automatically returned to the pool and made available for others. You can also return it early from the pool detail page by unassigning it.

Returned environments may be refreshed, reused, or deleted depending on the pool's expiration strategy.

Next