Salesforce Sandbox Manager

Manage Salesforce sandboxes centrally, safely, and consistently — without giving developers production access.

Sandbox Manager is an unlocked Salesforce package plus an sf CLI plugin. Teams install the package on one dedicated CICD sandbox; that sandbox is the only component with production access, held through a Named Credential using the OAuth 2.0 JWT Bearer flow. Developers and CI pipelines talk only to the CICD sandbox.

 Developers / CI              CICD sandbox                      Production
 ---------------              ------------                      ----------

                              +-------------------+             +-------------+
  sf CLI  --+                 |  Sandbox Manager  |             | Tooling API |
  LWC     --+--- Apex REST -->|  package (ns:tro) |--JWT/HTTPS->| SandboxInfo |
  Apex    --+                 +-------------------+             +-------------+
                              via Named Credential
                              Sandbox_Manager_Production

Why

Getting a fresh feature sandbox in a Salesforce project usually means asking an admin with production access and waiting for a clone to finish. Keeping shared CI/CD sandboxes fresh means someone remembers to refresh them. Sandbox Manager automates both:

• Sandbox pools — keep N pre-created clones of a source sandbox ready. A developer claims one in seconds instead of waiting for a clone:

  sf sandbox-manager claim --template dev4x1 --purpose ABC-123

  After use, the sandbox is deleted (not silently reused), and the pool replenishes itself.

• Scheduled refresh — manage exactly one named sandbox (for example a CI build or beta-data sandbox) and refresh it automatically every N days, including automatic activation. Pipelines gate on readiness:

  sf sandbox-manager status --template beta-dataset --fail-if-not-ready
  sf sandbox-manager wait --sandbox beta --timeout 180

Features

• Template-based clone pools with a configurable target of available sandboxes, automatic replenishment, and smallest-free-index naming (dev4x1x001 … dev4x1x999)
• Scheduled refresh of singleton sandboxes, with adoption of existing production sandboxes and automatic activation
• Claims with per-user limits, per-user overrides, purpose tracking, and an explicit delete lifecycle (Salesforce's license refresh intervals are handled by automatic retries)
• License capacity guard so the pool never over-consumes purchased sandbox entitlements; forced claims are possible but explicit
• Self-rescheduling reconciliation that keeps local state and production in sync, retries transient failures, and emails admins after repeated failures
• Release channel control per template (Salesforce default, Preview, Non-Preview) where the org has the preview sandbox feature
• CLI plugin for developers and CI (claim, mine, list, status, wait, delete, install) and a Lightning claim component for non-CLI users
• Guarded records: direct edits to lifecycle records are blocked by a trigger guard; administrative authority comes from an explicit custom permission, not object CRUD

Getting started

1. Install the plugin: sf plugins install @sfcicd/sandbox-manager
2. Install the package on your CICD sandbox: sf sandbox-manager install --target-org <cicd>
3. Follow the Setup Guide for production authentication (JWT Bearer flow) — the careful part, documented step by step with the common pitfalls — and create your first template.

Documentation

• Setup Guide — install + production authentication (start here)
• User Guide — templates, CLI, LWC, admin operations, troubleshooting
• Architecture & Design — data model, lifecycle, reconciliation rules
• Security & Threat Model
• Tooling API Notes — validated production API behavior
• Publishing Guide — releasing the package and the CLI

Repository layout

• force-app/ — Salesforce unlocked package (namespace tro)
• cli/ — Salesforce CLI plugin (@sfcicd/sandbox-manager)
• docs/ — documentation

Status

The package implements the service layer, Apex REST API, reconciliation job, scheduled refresh management, production Tooling API adapter, Lightning claim component, and the CLI plugin. The production Tooling API contract has been validated against a real production org (see Tooling API Notes).

Before a production rollout, complete the Setup Guide end to end in your CICD sandbox and confirm the connection test in step B7.

License

Licensed under the Apache License 2.0. See NOTICE.