To test our [system](../../core-concepts/#system) we need some [experiences](../../core-concepts/#experience).

## Prerequisites

Before creating experiences, you need to configure ReSim to access your experience data. See the [Experience Data Sources](../experience-data-sources/) guide for instructions on setting up access to:

- [AWS S3](../experience-data-sources/#aws-s3)
- [Google Cloud Storage](../experience-data-sources/#google-cloud-storage)
- [Foxglove Data Platform](../experience-data-sources/#foxglove-data-platform)
- [Local paths](../experience-data-sources/#local-experiences) in your build container

## Experience locations

Each experience can have multiple locations. In many cases, a single location is sufficient, but it can be helpful to store MCAPs recorded from different sources in different locations. [Assets](../assets/) that are common across all (or many) experiences are also supported in ReSim via a separate path.

ReSim supports the following location prefixes:

| Source               | Prefix        | Example                               |
| -------------------- | ------------- | ------------------------------------- |
| AWS S3               | `s3://`       | `s3://my-bucket/experiences/exp_001/` |
| Google Cloud Storage | `gs://`       | `gs://my-bucket/experiences/exp_001/` |
| Foxglove             | `foxglove://` | `foxglove://rec_abc123def456`         |
| Local                | None          | `/experiences/my-scenario/`           |

For cloud storage locations (S3, GCS), each location should have a unique prefix containing the input files. Anything contained in that prefix will be treated as the same experience and downloaded into your tasks. We recommend using a prefix structure that represents your ReSim projects:

Text

```
📂 .
├── 📂 project_a
│  └── 📂 experiences
│     └── 📂 experience_56ccce99
│        └── ⚙️ test_file
│
└── 📂 project_b
   └── 📂 experiences
      └── 📂 experience_679bef80
         └── ⚙️ test_file
```

### How experience files are accessed

For cloud-based experiences (S3, GCS, Foxglove), files are copied into `/tmp/resim/inputs/` when the experience build runs. If you use *multiple locations*, all files are copied directly into the `inputs` directory. Take care to ensure there are no file or directory name clashes at the root of the locations.

Avoiding file clashes with multiple locations

If your experience has two locations with the same directory structure:

Text

```
s3://your-bucket/experience1      s3://your-bucket/experience2
└── mcaps                         └── mcaps
    └── log.mcap                      └── log.mcap
```

The `mcaps/log.mcap` file will clash - one will overwrite the other in `/tmp/resim/inputs/`.

**Solution:** Change the path or filename to ensure uniqueness. For example, use distinct directory names:

Text

```
s3://your-bucket/experience1      s3://your-bucket/config
└── mcaps                         └── params.yaml
    └── log.mcap
```

This results in:

Text

```
/tmp/resim/inputs/
├── mcaps/
│   └── log.mcap
└── params.yaml
```

[Experience caching](../../guides/experience-caching/) is enabled by default, so we only copy files that have been added or changed since the last run.

For local experiences, files remain at their original location and you access them using the path from `/tmp/resim/test_config.json`. See [Local Experiences](../experience-data-sources/#local-experiences) for details.

## Experience timeouts

Each experience has a timeout. This is the maximum amount of time that a build can run for a given experience. If the build does not finish running before the timeout is reached, it will be sent a SIGTERM and then a SIGKILL after a grace period.

The default timeout is 1 hour, but you can specify a different timeout when creating an experience.

## Creating an experience

You can create new experiences like so:

Bash

```
resim experiences create \
    --project "my-project" \
    --name "Experience_56ccce99" \
    --description "In this experience, we test that our robot can navigate to the goal without colliding with any other agents." \
    --locations "s3://my-experiences-bucket/project_hal9000/experiences/experience_56ccce99/" \
    --systems "perception" "localization" \
    --tags "navigation" "collision-avoidance"
```

This command should return a message containing the UUID of the created experience, and it should now be browsable through the [ReSim app](https://app.resim.ai).

The `--systems` flag enables you to specify any [systems](../../core-concepts/#system) that this experience is compatible with. You can specify multiple systems by providing multiple system names or IDs.

The `--tags` flag allows you to apply tags to the experience for better organization and filtering. You can specify multiple tags by providing multiple tag names or IDs.

Optional flags are:

Bash

```
    --timeout "1h10m" # the maximum expected duration of the container \
    --environment-variable "SYSTEM_CONFIGURATION=Foo" # many allowed \
    --environment-variable "AN=other" \
    --profile "left-arm" # a docker compose profile to select the subset of compose services to run \
```

### Examples with different sources

**AWS S3:**

Bash

```
resim experiences create \
    --project "my-project" \
    --name "S3 Experience" \
    --description "An experience stored in S3" \
    --locations "s3://my-bucket/experiences/exp_001/"
```

**Google Cloud Storage:**

Bash

```
resim experiences create \
    --project "my-project" \
    --name "GCS Experience" \
    --description "An experience stored in GCS" \
    --locations "gs://my-gcs-bucket/experiences/exp_001/"
```

**Foxglove:**

Bash

```
resim experiences create \
    --project "my-project" \
    --name "Foxglove Experience" \
    --description "An experience stored in Foxglove" \
    --locations "foxglove://rec_abc123def456"
```

**Local:**

Bash

```
resim experiences create \
    --project "my-project" \
    --name "Local Experience" \
    --description "An experience stored locally in the build container" \
    --locations "/experiences/my-scenario/"
```

## Updating an experience

You can update various aspects of an experience, including its systems and tags:

Bash

```
resim experiences update \
    --project "my-project" \
    --experience "Experience_56ccce99" \
    --name "Updated Experience Name" \
    --description "Updated description" \
    --locations "s3://my-experiences-bucket/project_hal9000/experiences/updated_experience/" \
    --timeout "2h" \
    --systems "perception" "planning" \
    --tags "updated-tag" "new-functionality"
```

When updating systems or tags, the provided lists will replace the existing systems and tags associated with the experience.

You can also add or remove individual systems from an experience:

Bash

```
resim experiences add-system \
    --project "my-project" \
    --system "<system name>" \
    --experience "Experience_56ccce99"

resim experiences remove-system \
    --project "my-project" \
    --system "<system name>" \
    --experience "Experience_56ccce99"
```

Similarly you can add and remove individual tags:

Bash

```
resim experiences tag \
    --project "my-project" \
    --tag "<tag string>" \
    --experience "Experience_56ccce99"

resim experiences untag \
    --project "my-project" \
    --tag "<tag string>" \
    --experience "Experience_56ccce99"
```