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 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 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. |
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 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
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.
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):
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):
# 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:
# 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:
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:
# 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:
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:
# 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:
- Log into your Developer account.
- Go to Developer > Developer Sandbox.
- Click the three dots to the right of the sandbox > Delete sandbox.