# Working with Simulation Files

One JSON file = One Hoverfly Simulation

This topic discusses

* how these files are stored in Hoverfly Cloud
* how they are applied to running services
* how to keep different versions of them synchronized
* how to upload and download them

### Terminology

* Services run instances of simulations.
* Services are running web servers and can be viewed from the Hoverfly Cloud dashboard
* Simulations are JSON files that represent an API simulation configuration - it's endpoints and matching configuration
* Simulation files are stored in a simulation library accessed from the menu in Hoverfly Cloud
* Simulations can be downloaded from, and uploaded to the simulation library
* Services can be started using a simulation file from the library. When started in this way they make their own copy of the simulation file and any changes made to it from within that service are independent of the master simulation file stored in the simulation library. In this way a single master simulation can be shared with many service instances which will each take their own copy.
* Services can also be started without a simulation file. In this case the service will have a simulation labelled (unsaved) when viewed from the dashboard.

### Considerations if you are running a service with an unsaved simulation

In this case the service will have a simulation labelled (unsaved) when viewed from the dashboard.

This implies that the simulation that the service is running does not have a master copy in the simulation library. It was started without a simulation, and any configuration done to the simulation in this service is only in this service and cannot be shared.

You need to follow the following steps to add the unsaved simulation to the simulation library before you can download it, or before it can be used by other services that might need to.

Step 1: Click on (unsaved) simulation

<figure><img src="/files/R9uXsrTlaD8zipLREdHA" alt=""><figcaption></figcaption></figure>

Step 2: Click down arrow and Export simulation as new

<figure><img src="/files/loMF94lqBJViVCSuYMjP" alt=""><figcaption></figcaption></figure>

Once you have exported the simulation it will appear in the simulation library from where it can be downloaded.

### Considerations if you are running a service with a simulation from the library

In this case the service will have a named simulation when viewed from the dashboard.

When the service was started, it was done so using a simulation file from the simulation library.

The version of the simulation running in the service is a separate copy of the master simulation file and can be changed independently of the simulation file stored in the library.

If you wish to keep the version running in the service separately from the version stored in the library you need to **export** is as a new simulation file, with a different name to the version already in the library.

<figure><img src="/files/6WkUiX1mFXYlLgPVuymc" alt=""><figcaption></figcaption></figure>

If you wish to overwrite the existing version in the library with any changes made to the version running in the service, you can **synchronize** the service's simulation with the library. This will overwrite what's in the library with what is currently in the service.

<figure><img src="/files/A5yaoGadWzslD0YEh5gn" alt=""><figcaption></figcaption></figure>

### Downloading simulations from the simulation library

Click the download icon next to the simulation from the simulation library.

<figure><img src="/files/7k7RDc3jjKL0Slco18lE" alt=""><figcaption></figcaption></figure>

### Uploading simulations to the simulation library

Click the Upload button from the simulation library

<figure><img src="/files/wY1TcNXn7T1H8Z9ZdZBX" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cloud.hoverfly.io/create-simulations/working-with-simulation-files.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.