Platform Sandbox Configure

Sandbox Lifecycle Management

Manage Salesforce sandbox environments through Connect REST API — list inventory, activate or discard completed refreshes, create and refresh sandboxes, and permanently delete sandboxes.

When This Skill Owns the Task

Use platform-sandbox-configure when the work involves:

• Listing or retrieving all sandboxes (GET /sandbox/reports)
• Getting details or status of a specific sandbox by name or by ID (07E prefix)
• Checking license usage and remaining capacity by license type (GET /sandbox/licenses)
• Activating a sandbox after a refresh completes (applying the refresh)
• Discarding a completed refresh (keeping existing sandbox data unchanged)
• Permanently deleting a sandbox to free up licenses
• Verifying activation or deletion completed
• Creating a new sandbox (Developer, Developer Pro, Partial Copy, or Full)
• Refreshing an existing sandbox with latest production data

Delegate elsewhere when the user is:

• Cloning a sandbox → Tooling API (SandboxInfo sObject)
• Generating a post-copy automation JSON config from an SOP → automation-sandbox-post-copy-config-generate
• Applying/running a post-copy automation JSON config against a sandbox → automation-sandbox-post-copy-configure

Help (Interactive Menu)

When the user types sandbox -help or sandbox help, respond with ONLY a text message showing the numbered operation list below. Do NOT call any API or tool — just display this menu and wait for the user to reply with a number.

The agent MUST respond with this exact markdown (not in a code block — render it directly as a bullet list):

Sandbox Lifecycle Management

1. Inventory & Details

• a. List all sandboxes — Names, types, statuses, IDs
• b. Get details (by name) — Status, license, config
• c. Get details (by ID) — Provide a 07E ID directly
• d. Check license usage — Available vs. used counts by license type

2. Create & Refresh

• a. Create a new sandbox — Dev, Dev Pro, Partial, Full
• b. Refresh a sandbox — Latest production data

3. Activate, Discard & Delete

• a. Activate a sandbox — Apply a completed refresh
• b. Discard a refresh — Reject, keep existing data
• c. Delete a sandbox — Permanent removal

4. Verify & Monitor

• a. Verify activation status — Check if activate completed
• b. Verify deletion status — Check if delete completed

5. Post-Copy Automation

• a. Create Post Copy Automation JSON Configs — Generate a config from an SOP
• b. Run Post Copy Automation — Apply a config JSON to a sandbox

Reply with a code (e.g. "3a") or describe what you need.

After the user replies, ask for the required input:

Execute the corresponding operation below. Exception: 5a/5b delegate — 5a → automation-sandbox-post-copy-config-generate; 5b → automation-sandbox-post-copy-configure. This skill does not implement post-copy automation; do not generate or apply a config directly.

API Base

CRITICAL: For sandbox operations in this skill, use the Connect REST API. Two discovery paths exist:

• By name: Call GET /sandbox/reports to list all sandboxes and find the matching one by sandboxName.
• By ID (07E prefix): Call GET /sandbox/sandboxes/{sandboxId} directly — do NOT call /sandbox/reports.

Both paths return sandbox records with sandboxId (prefix 07E) which is required for all lifecycle mutation operations.

sf api request rest "/services/data/v66.0/sandbox/reports" --method GET

See references/api-response-shapes.md for the full response shape.

IMPORTANT: Do NOT use Tooling API (SandboxInfo/SandboxProcess) for discovery — mutation endpoints require the Connect REST API's sandboxId (07E), NOT SandboxInfo.Id (0GQ) or SandboxProcess.Id (0GR).

NEVER use SOQL / run_soql_query / sf data query for lifecycle reads (status, inventory, details, license, pending-activation). This data lives ONLY in the Connect REST API — no SObject returns it. (sf data query --use-tooling-api on SandboxInfo is still valid for Create/Refresh mutations, not a lifecycle read.)

Report API results exactly as they come back — never invent an error or a cause. count: 0 is a successful result (sandbox absent) — record not_found, don't reinterpret as a failure or retry via SOQL. If the API errors, capture the error body verbatim — do NOT speculate why (e.g. "must be a scratch org"); this endpoint doesn't report org edition/type, so any such guess is a fabrication.

Required permission: ManageSandboxes

Irreversible Actions — Always Confirm First

Operations

1. List Sandbox Inventory

Endpoint: GET /services/data/v66.0/sandbox/reports

Returns a list of all sandboxes with their IDs, names, statuses, and license types.

sf api request rest "/services/data/v66.0/sandbox/reports" --method GET

See references/api-response-shapes.md for the full response shape.

Use when: User asks "show me all sandboxes", "how many sandboxes do I have", "what's the status of my sandboxes"

Key response fields:

• sandbox.sandboxId (07E prefix) — Required for all mutation operations
• sandbox.sandboxName — The sandbox name (top-level field)
• sandbox.license — Developer, Developer Pro, Partial Copy, Full
• sandbox.isPendingActivation — true if refresh is pending activation
• sandbox.canActivate / canDelete / canDiscard — Permission flags

2. Get Sandbox Details

Endpoint: GET /services/data/v66.0/sandbox/sandboxes/{sandboxId}

Returns detailed info for a specific sandbox.

Use when: User asks about a specific sandbox's status, configuration, or metadata.

Key response fields:

• status — Active, Pending Activation, Activating, Completed, etc.
• isPendingActivation — true if a refresh completed and awaits user decision
• sandboxType — Developer, DeveloperPro, PartialCopy, Full
• sourceId — ID of the source org

3. Activate Sandbox (Apply Refresh)

Endpoint: PATCH /services/data/v66.0/sandbox/activate/{sandboxId}

CRITICAL DOMAIN RULE: This operation ONLY applies to sandboxes with a completed refresh in "Pending Activation" state. It applies the refreshed data to the sandbox. It does NOT "bring an inactive sandbox online" or "start" a sandbox.

Pre-conditions:

• Sandbox must be in Pending Activation status
• A refresh must have completed successfully
• User must have ManageSandboxes permission

Before calling PATCH /activate:

• Confirmed sandbox is in Pending Activation status via GET /sandbox/sandboxes/{id} (isPendingActivation: true)
• Confirmed a refresh has completed successfully
• Received explicit user confirmation — this overwrites the sandbox with the refreshed data and cannot be undone

Use when: User says "activate it", "apply the refresh", "use the latest data"

After activation: The sandbox runs with the newly refreshed production data.

4. Verify Activation

Endpoint: GET /services/data/v66.0/sandbox/sandboxes/{sandboxId}

Poll this endpoint after activation to confirm status changed to Active. This is a verification step, not a standalone user action.

Use when: Agent needs to confirm activation completed (called automatically after activate).

5. Discard Sandbox (Reject Refresh)

Endpoint: DELETE /services/data/v66.0/sandbox/discardsandbox/{sandboxId}

CRITICAL DOMAIN RULE: This operation ONLY applies to sandboxes with a completed refresh in "Pending Activation" state. It rejects the refresh — the existing sandbox continues running with its current data unchanged. It does NOT:

• Free up licenses
• Soft-delete or hide the sandbox
• Reset the sandbox to match production

Pre-conditions:

• Sandbox must be in Pending Activation status
• A refresh must have completed

Before calling DELETE /discardsandbox:

• Confirmed sandbox is in Pending Activation status via GET /sandbox/sandboxes/{id} (isPendingActivation: true)
• Confirmed this is a discard (reject refresh), NOT a delete (permanent removal)
• Received explicit user confirmation — the refresh data will be permanently lost and cannot be undone

Use when: User says "discard the refresh", "keep existing data", "don't apply the refresh", "reject the refresh"

WARNING: Discard is not reversible. The user will need to trigger a new refresh if they want fresh production data later.

6. Delete Sandbox (Permanent)

Endpoint: DELETE /services/data/v66.0/sandbox/deletesandbox/{sandboxId}

Permanently removes a sandbox and frees the license.

Pre-conditions:

• Sandbox must exist
• User must have ManageSandboxes permission

Before calling DELETE /deletesandbox:

• Surfaced sandbox details (name, license, status) with user and received explicit delete approval

Use when: User says "delete this sandbox", "remove it permanently", "free up the license"

WARNING: This is irreversible. Always confirm with the user before executing. Surface the sandbox name, license, and status as a safety check.

If asked to restore a deleted sandbox: No recovery path is documented today — escalate to Support rather than guessing at one.