Use the Business Central Sandbox Environment

A Business Central sandbox is an isolated environment that runs independently of production. It contains a separate database, separate users, and separate extension installations. Changes you make in a sandbox, whether publishing an extension, modifying data, or testing a configuration, have no effect on the production tenant.

For AL development, working in a sandbox is not optional. Sandboxes let you iterate quickly, break things without consequence, and test against realistic data before any code reaches a live environment.

Prerequisites

A Microsoft 365 or Dynamics 365 Business Central subscription
Admin access to the Business Central Admin Center
Visual Studio Code with the AL Language extension installed
Basic familiarity with launch.json configuration

Steps

1. Create a sandbox from the Business Central Admin Center

Navigate to the Business Central Admin Center at https://businesscentral.dynamics.com/[tenant]/admin.
In the left menu, select Environments.
Select New to create a new environment.
Set Environment Type to Sandbox.
Enter a name (e.g. Dev-Sandbox or Test-Feature-X).
Choose whether to create a blank environment or copy from production.
Select Create and wait for provisioning to complete (typically 5–15 minutes).

Blank sandbox, starts with demo data or no data. Useful for early development when you are building from scratch and do not need production records.

Copy from production, clones the production database, including all live data and installed extensions. Useful for debugging issues that only appear with real data. Note that copying production data into a sandbox means that data is subject to your organisation’s data handling policies.

2. Understand sandbox limitations

Free (included) sandboxes created in this way have the following constraints:

Constraint	Detail
Reset cycle	Free sandboxes are reset approximately every 30 days
No production connection	No live data sync from production
Extension limitations	Some AppSource apps require a paid license to install
Performance	Sandboxes share infrastructure and may be slower than production
Data persistence	Data is lost on reset unless you export it beforehand

Paid sandbox environments (additional capacity units) do not reset on a 30-day cycle and are suitable for longer-running projects.

3. Connect VS Code to an online sandbox

Open or create launch.json in your AL project’s .vscode folder. Add a configuration that points to your sandbox.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Dev Sandbox",
      "request": "launch",
      "type": "al",
      "environmentType": "Sandbox",
      "environmentName": "Dev-Sandbox",
      "tenant": "mytenant.onmicrosoft.com",
      "startupObjectId": 22,
      "startupObjectType": "Page",
      "authentication": "UserPassword",
      "breakOnError": "All",
      "launchBrowser": true
    }
  ]
}

environmentName must exactly match the name you gave the sandbox in the Admin Center.
tenant is your Microsoft 365 tenant domain.
authentication is typically "UserPassword" for online environments or "Windows" for on-premises.

Press F5 in VS Code to compile, publish to the sandbox, and open a browser to the startup page.

4. Use a local Docker container with BcContainerHelper

For offline development or when you need full control over the BC version, you can run Business Central in a local Docker container using the BcContainerHelper PowerShell module.

Install the module and create a container:

Install-Module BcContainerHelper -Force

New-BcContainer `
    -accept_eula `
    -containerName "bc-dev" `
    -artifactUrl (Get-BcArtifactUrl -type sandbox -country "w1" -version "24") `
    -auth NavUserPassword `
    -credential (Get-Credential) `
    -updateHosts

Connect VS Code to the local container by using "environmentType": "OnPrem" in launch.json:

{
  "name": "Local Docker BC",
  "request": "launch",
  "type": "al",
  "environmentType": "OnPrem",
  "server": "http://bc-dev",
  "serverInstance": "BC",
  "authentication": "UserPassword",
  "startupObjectId": 22,
  "startupObjectType": "Page",
  "breakOnError": "All"
}

Replace "bc-dev" with the hostname or IP of your Docker container. The serverInstance is typically "BC" by default in BcContainerHelper-created containers.

Local containers are useful when:

You need to work without internet access
You want to test against a specific BC version
You want complete control over data and resets

Drawbacks:

Requires Docker Desktop (Windows or macOS) with sufficient RAM (minimum 8 GB, 16 GB recommended)
You manage updates and container maintenance yourself

5. Download symbols from the sandbox

Before writing AL code that references base application objects, download the symbols from your target environment.

In VS Code, press Ctrl + Shift + P and run AL: Download Symbols. VS Code will connect to the environment defined in the active launch.json configuration and download the .alpackages into your project folder.

Re-download symbols whenever:

You update to a new BC version
A dependency extension is updated on the sandbox
You switch to a different sandbox environment

6. Manage multiple sandbox configurations

On most projects you will have at least two configurations in launch.json: one for a development sandbox and one for a UAT (user acceptance testing) sandbox. You can also add a local Docker configuration.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Dev Sandbox",
      "request": "launch",
      "type": "al",
      "environmentType": "Sandbox",
      "environmentName": "Dev-Sandbox",
      "tenant": "mytenant.onmicrosoft.com",
      "authentication": "UserPassword",
      "startupObjectId": 22,
      "startupObjectType": "Page"
    },
    {
      "name": "UAT Sandbox",
      "request": "launch",
      "type": "al",
      "environmentType": "Sandbox",
      "environmentName": "UAT-Sandbox",
      "tenant": "mytenant.onmicrosoft.com",
      "authentication": "UserPassword",
      "startupObjectId": 22,
      "startupObjectType": "Page"
    },
    {
      "name": "Local Docker",
      "request": "launch",
      "type": "al",
      "environmentType": "OnPrem",
      "server": "http://bc-dev",
      "serverInstance": "BC",
      "authentication": "UserPassword",
      "startupObjectId": 22,
      "startupObjectType": "Page"
    }
  ]
}

Switch between configurations using the dropdown in the VS Code Run and Debug panel (Ctrl + Shift + D) before pressing F5.

7. Follow a practical development workflow

A reliable workflow for individual feature development looks like this:

Create a feature-specific sandbox, if the project is large, avoid sharing a single sandbox across developers. Each developer or feature branch should have its own sandbox to prevent conflicts when publishing extensions.
Work on a Git feature branch, keep code changes on a branch. Commit regularly.
Publish frequently, use Ctrl + F5 (publish without debugging) for fast iteration. Use F5 when you need to step through code with breakpoints.
Run unit tests before considering a feature complete, see How to Write and Run AL Unit Tests in Business Central.
Reset or refresh the sandbox when data becomes inconsistent, in the Admin Center, select the sandbox and use Reset to restore it to a clean state.
Do not publish directly to production, always use a separate UAT environment before deploying to production via Extension Management.

Common Mistakes

Using a single shared sandbox for all developers, extension conflicts and data issues accumulate quickly. Give each developer their own sandbox or use Docker containers locally.
Forgetting to increment the extension version in app.json before publishing a new build, Business Central will reject the upload if the version already exists on the tenant.
Developing against production, always work in a sandbox. Even read-only access to production during development is risky if you accidentally publish to the wrong environment.
Not re-downloading symbols after a BC update, outdated symbols cause false compilation errors and missing IntelliSense.

For the full publish workflow once your feature is ready to move out of the sandbox, see How to Publish and Install Extensions in Business Central.