# Overview of developer sandboxes

> Status: Beta

> Build and test your integration using Rippling’s developer sandboxes.

A developer sandbox is an isolated Rippling company provisioned with mock mid-size company data (includes employee and configuration data). It allows you to build, deploy, and test in Rippling without affecting real employee or HR data.

> **Developer sandboxes vs. Rippling sandboxes:**
> Developer sandboxes are test environments seeded with mock company data, whereas Rippling sandboxes are an exact copy of a customer’s data extracted into a test environment. See [Overview of sandbox environments](https://help.rippling.com/article?articleId=2bhzvu1ybO0Mq6Fm73mEE4) for more information on Rippling sandboxes (requires a Rippling login to access).

When building for the Developer Program, you will need to create two separate sandboxes from your primary Developer account. You’ll use one sandbox as the **editor**, and the other as the **installer**.

| Sandbox type | Package link mode | Purpose | Notes |
| --- | --- | --- | --- |
| Editor sandbox | `EDIT` | Deploy local metadata and functions, bundle components into versions, and publish releases. | A package can only be linked to one editor sandbox at a time. |
| Installer sandbox | `INSTALL` | Install published package releases and verify the customer experience. | A published version can be installed across multiple installer sandboxes. |

> **Rippling:**
> A sandbox becomes an editor or installer only after it has been linked to the package using the package’s `--mode` flag (`EDIT` or `INSTALL`). See [Build for the Developer Program](https://developer.rippling.com/documentation/rippling-platform/developer-program/build) for more details.

Each package link mode supports different CLI commands:

-   **Editor sandbox** (`EDIT`): `project deploy`, `function deploy`, `package version next`, `package version components`, `package version publish`
-   **Installer sandbox** (`INSTALL`): `package install`, `package upgrade`, `package uninstall`, `package installation status`

* * *

## Requirements

-   Access to developer sandboxes is gated behind the Developer Program, which is currently in a closed beta.
-   Sandboxes must be created and linked from the primary Developer account.

* * *

## Setup

### Provision sandboxes

> **Rippling:**
> There is a sandbox limit of **three sandboxes per Developer account**. If you reach your company's quota limit, the CLI returns an `HTTP 403: You've already created the maximum number of sandboxes` error. In this case, [reuse](https://developer.rippling.com/documentation/rippling-platform/rippling-cli/sandboxes#rippling-sandbox-use) or [delete](https://developer.rippling.com/documentation/rippling-platform/rippling-cli/sandboxes#rippling-sandbox-delete) an existing sandbox.

Upon setup, create two sandboxes: one for editing and another for installing. Pass `--context developer-account` on creation so that sandboxes are created from the primary Developer account.

If at any point the Developer account has been renamed during setup, replace `developer-account` with the account’s new name.

```bash
rippling --context developer-account sandbox create --name "Editor" --type developer --json

rippling --context developer-account sandbox create --name "Installer" --type developer --json
```

When creating sandboxes, you can optionally define the company size (`SMALL` or `MEDIUM`):

```bash
cat > editor-config.json <<'EOF'
{
  "developer": {
    "company_size": "MEDIUM"
  }
}
EOF
```

Each sandbox output provides two identifiers:

-   `id`: Unique internal ID (e.g., sb\_12345).
-   `handle`: Short identifier

Create a sandbox in the Rippling UI by going to **Developer** > **Developer Sandbox** > click **Create sandbox**. Add the sandbox name, an optional description, and click **Create sandbox**.

### Save contexts & map company IDs

Switch into each sandbox context to register it locally and resolve the `companyID` (required to link packages):

```bash
# Register the editor context using its handle
rippling --context developer-account sandbox use \
  --alias "<EDITOR_HANDLE>" \
  --context-name sandbox-editor

# Capture the company ID for package linking
export EDITOR_COMPANY_ID=$(rippling config context get --context sandbox-editor --json | jq -r '.companyID')

# Register the installer context
rippling --context developer-account sandbox use \
  --alias "<INSTALLER_HANDLE>" \
  --context-name sandbox-installer

export INSTALLER_COMPANY_ID=$(rippling config context get --context sandbox-installer --json | jq -r '.companyID')
```

### Link sandboxes to your package

Run all linking commands from `developer-account`:

```bash
# Link editor sandbox in `EDIT` mode
rippling --context developer-account package sandbox link \
  --package-key "<PACKAGE_KEY>" \
  --sandbox-company-id "$EDITOR_COMPANY_ID" \
  --mode EDIT \
  --json

# Link installer sandbox in `INSTALL` mode
rippling --context developer-account package sandbox link \
  --package-key "<PACKAGE_KEY>" \
  --sandbox-company-id "$INSTALLER_COMPANY_ID" \
  --mode INSTALL \
  --json
```

If the linking returns a tracking ID (`tracker_id`), check the status until completion:

```bash
rippling --context developer-account package sandbox status --tracker-id "<TRACKER_ID>" --json
```

* * *

## Manage

### Fetch sandboxes & sign in

Run all commands from your primary Developer account:

```bash
# List all sandboxes
rippling --context developer-account sandbox list --json

# Fetch a specific sandbox
rippling --context developer-account sandbox get --id "<SANDBOX_ID>" --json
```

To sign in to your sandbox account:

```bash
rippling --context developer-account api sandbox login --alias "<SANDBOX_HANDLE>" --context-name sandbox-installer
```

Log into your sandbox in the Rippling UI by going to **Developer** > **Developer Sandbox** > click **Log in** to the right of the sandbox.

### Manage default contexts

Running `sandbox use` sets that sandbox as your active default context, allowing later commands to omit the `--context` flag.

To switch your context between different sandboxes:

```bash
# View active context
rippling config default-context show

# Switch active context to installer
rippling config default-context set --context sandbox-installer

# Switch active context back to editor
rippling config default-context set --context sandbox-editor
```

* * *

## Delete

Use `rippling --context developer-account sandbox delete --id "<SANDBOX_ID>"` to delete an existing sandbox. Once a sandbox is deleted, both the packages and changes made in the sandbox are unable to be retrieved.

To delete a sandbox in the Rippling UI:

1.  Log into your Developer account.
2.  Go to **Developer** > **Developer Sandbox**.
3.  Click the three dots to the right of the sandbox > **Delete sandbox**.

* * *

## See also

-   [Get started with the Developer Program](https://developer.rippling.com/documentation/rippling-platform/developer-program/get-started)
-   [Apply to the Developer Program](https://developer.rippling.com/documentation/rippling-platform/developer-program/apply)
-   [Build for the Developer Program](https://developer.rippling.com/documentation/rippling-platform/developer-program/build)
-   [Get started with the Rippling CLI](https://developer.rippling.com/documentation/rippling-platform/rippling-cli/get-started)
-   [When to use Rippling primitives](https://developer.rippling.com/documentation/rippling-platform/custom-solutions/rippling-primitives)

Source: https://developer.rippling.com/documentation/rippling-platform/developer-program/sandboxes

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Public pages have a Markdown version at the same URL with .md added.