# Sandbox

Sandbox makes testing energy apps simple and effective by providing instant access to virtual devices of any kind. This guide explains Sandbox’s core features and how to use it to simulate real-world scenarios during application development.

## What is Sandbox?

![sandbox infrastructure diagram](https://developers.enode.com/images/sandbox/enode-sandbox_infrastructure.png)

Sandbox is a virtual environment for your energy apps. Instead of connecting to real devices, you can use virtual ones that you control instantly.

### Key features

- **Supports all asset types** – Create and control vehicles, chargers, batteries, and more
- **Instant state control** – Modify asset states to test any real-world condition
- **Webhook integration** – Observe live updates directly in the Sandbox UI
- **Virtual accounts** – Simulate vendor accounts and user scenarios with multiple devices
- **Intervention testing** – Test error and edge-case scenarios safely

Limitations: The current version of Sandbox differs from real-world behavior.  It does not yet support Smart Charging, and values do not automatically change over time.For example:- When a vehicle is charging, the battery level stays static.- When an HVAC is cooling, the current temperature will not decrease.

## Why Sandbox?

Developing for energy devices can be challenging due to:

- Limited access to physical devices for testing
- Dependence on third-party hardware outside your control
- Long waiting times for specific device states
- Complex scenarios, such as users with multiple devices per vendor

**Sandbox solves these challenges**, enabling faster, lower-cost, and more reliable development.

## Quick start

You can start working with assets in two ways:

1. [**Create a virtual account**](https://developers.enode.com/docs/sandbox#virtual-accounts) with one or more devices and link it to a user
2. [**Create an asset directly**](https://developers.enode.com/docs/sandbox#creating-a-new-asset) and let Sandbox automatically create and link a virtual account for you

Tip: Which way to choose?: Start with a **virtual account** if you want to test linking flows (for example with LinkUI) or simulate complex user setups with multiple devices.**Skip ahead** to [create a new asset](https://developers.enode.com/docs/sandbox#creating-a-new-asset) if you just want to experiment with a single asset quickly.

## Virtual accounts

Virtual accounts represent a user’s OEM account in Sandbox. They let you recreate real-world setups, for example a user owning several devices per vendor, and let you test every stage of the linking process.

You can:

- Create accounts with one or more devices across asset types (e.g. vehicles, batteries, etc)
- Link accounts automatically or via LinkUI to test the full linking flow
- Add or remove devices after linking to simulate real-world API behavior

### Virtual accounts list

To create and manage virtual accounts, go to your Sandbox client in the [customer dashboard](https://developers.enode.com/dashboard) and select **Virtual accounts** from the left-hand menu.

![List of virtual accounts](https://developers.enode.com/images/sandbox/enode-sandbox_virtual_accounts-list-view.png)

The list shows all virtual accounts in your Sandbox client. You can:

- Create a new virtual account
- Search, filter, and access existing virtual accounts

### Creating a new vendor account

![Create new virtual account dialog](https://developers.enode.com/images/sandbox/enode-sandbox_create_new_vendor_account-dialog.png)

1. In the **Virtual accounts** view, click **Create new**
2. Select the vendor
3. Add a display name
4. Click **Create** to finish

Note: A new virtual account starts empty and unlinked. To link it to a user, add at least one device first.

### Adding a device to a virtual account

![Create new device dialog](https://developers.enode.com/images/sandbox/enode-sandbox_create_new_device-dialog.png)

1. Select the virtual account you want to add a device to
2. Under **Virtual devices**, click **Create device**
3. If the vendor supports more than one asset type, select which type to add
4. Choose the model, year and display name
5. Click **Create**

If this is your first device, you can now link the virtual account to a user.

### Linking a virtual account to a user

![Link virtual account dialog](https://developers.enode.com/images/sandbox/enode-sandbox_link_virtual_account-dialog.png)

You can link a virtual account to a user in two ways:

1. **Via LinkUI** – Use this option to test the full linking flow
2. **Automatic linking** – Use this to start working directly with the account’s assets

#### **Linking via LinkUI**

To link via LinkUI:

- [Create a new linking session](https://developers.enode.com/docs/getting-started#step-3-link-a-device-through-link-ui) for a user
- Use the **virtual account credentials** (username and password) when prompted in [LinkUI](https://developers.enode.com/docs/link-ui/introduction)

#### **Automatic linking**

To link automatically:

1. Open the virtual account
2. Click **Link**
3. Select an existing user ID or enter a new one
4. Click **Link**

In both cases, the linked assets will appear in the [Asset list](https://developers.enode.com/docs/sandbox#managing-assets).

## Working with assets

Assets in Sandbox work the same way as assets in a production client. They represent individual devices.
The difference is that in Sandbox, you have full control: you can create, view, edit, and monitor assets to simulate real-world behavior instantly.

### Creating a new asset

![dialog to create a new asset](https://developers.enode.com/images/sandbox/enode-sandbox_new_asset-dialog.png)

Assets are automatically created when you link a [virtual account](https://developers.enode.com/docs/sandbox#virtual-accounts) to a user.

If you want to test a single device or start experimenting quickly, you can also create a linked asset directly. Sandbox will automatically create a virtual account and user for you, or let you add the asset to an existing virtual account.

1. In the **Assets** view, click **Create new**
2. Select the asset type, vendor, and model
3. Add a display name
4. Choose an existing linked [virtual account](https://developers.enode.com/docs/sandbox#virtual-accounts) or create a new one
5. Your new asset will appear in the [Asset list](https://developers.enode.com/docs/sandbox#managing-assets)

Virtual accounts: When you choose to create a new virtual account, this vendor account will automatically be linked to a new user.If you want to create a vendor account linked to a specific user or test linking in Link UI, you can do all that under [virtual accounts](https://developers.enode.com/docs/sandbox#virtual-accounts).

## Managing assets

![The asset list view](https://developers.enode.com/images/sandbox/enode-sandbox_asset-list-view.png)

The **Asset list** shows all assets in your Sandbox client. You can:

- Create new assets
- Filter by asset type
- Search by name or ID

Selecting an asset opens the [Asset view](https://developers.enode.com/docs/sandbox#working-with-an-asset) where you can:

- [View the asset’s current state](https://developers.enode.com/docs/sandbox#1-viewing-the-assets-state)
- [Edit its state](https://developers.enode.com/docs/sandbox#2-editing-the-assets-state)
- [Monitor webhook events](https://developers.enode.com/docs/sandbox#3-monitoring-events)

## Working with an asset

The **Asset view** is your main workspace for testing and simulating device behavior.

In Sandbox, working with an asset means editing the state of its underlying virtual device to reflect real-world actions, for example plugging in a vehicle, charging a battery, or an inverter producing power. This lets you simulate both user actions and automatic device behavior directly in the UI.

### 1. Viewing the asset's state

![Asset state view](https://developers.enode.com/images/sandbox/enode-sandbox_asset_state.png)

The main section displays the asset’s state, which updates in real time when:

- You edit the state
- A colleague updates the same asset
- The API triggers a change

Asset view guide: For full details on Asset view features available in both Sandbox and production, see the [Asset view guide](https://developers.enode.com/docs/asset-view/asset-view).

### 2. Editing the asset's state

![Asset field edit dialog](https://developers.enode.com/images/sandbox/enode-sandbox_assset-edit-dialog.png)

To edit an asset's state:

1. Click **Edit** next to a field
2. Update the value and review the **preview** of the resulting state
3. Confirm the change

Most fields trigger automatic side effects.  
For example, changing a vehicle’s `powerDeliveryState` from `PLUGGED_IN:CHARGING` to `PLUGGED_IN:COMPLETE` automatically sets `isCharging` to `false`.

Each field also includes a **description** that explains how it behaves in real life and what events typically cause it to change.

Not all fields are editable: Certain fields, such as `model` or `chargeTimeRemaining`, cannot be changed because they are static or derived from other values.

### 3. Monitoring events

![Events feed](https://developers.enode.com/images/sandbox/enode-sandbox_events-dialog.png)

The **Asset View** in Sandbox automatically listens for [webhook](https://developers.enode.com/docs/webhooks) updates.

Any changes to the asset state, whether made by you, a teammate working on the same asset, or through the API, are received in real time and immediately reflected in the UI.

The **Events Feed** provides detailed information about the updates received for the asset:

- Webhooks reflecting state changes.
- A record of state changes performed on the asset via the Sandbox UI.

This ensures you can associate every modification with its associated webhook.

![Webhook event in the events feed](https://developers.enode.com/images/sandbox/enode-sandbox_webhook-dialog.png)

By clicking on one of the **webhooks** in the feed you will have access to:

- A summary of all the fields that have updated
- The raw JSON body of the webhook

Webhooks guide: Learn more about webhooks in the [webhooks guide](https://developers.enode.com/docs/webhooks).

## Testing Actions

When you create an [action](https://developers.enode.com/docs/integration-guide/controlling-devices) in the API, Enode will attempt to execute that action on the device until it succeeds, fails (times out), or is cancelled.

**In the real world**, an action succeeds when the physical asset transitions to the desired state.

**In Sandbox**, you must manually change the virtual asset’s state to the desired outcome to simulate a successful action. This also allows you to test failure scenarios by letting the action time out or setting the asset to an unintended state.

For more details on different test cases, refer to our [Sandbox testing guide](https://developers.enode.com/docs/integration-guide/testing#testing-in-sandbox).

[Read next: Asset View](https://developers.enode.com/docs/asset-view/asset-view)