> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/dsx-air/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/dsx-air/_mcp/server.

# Starting and Stopping Simulations

```python
# Imports (run once)

from air_sdk import AirApi, SimState
from air_sdk.endpoints import Simulation
```

```python
# Authentication (run once)
api = AirApi.with_ngc_config()
# OR api = AirApi.with_api_key(api_key="...")
# OR api = AirApi.with_device_login(email="...", org_num="...")
#    ^ use in terminal only — not supported in Jupyter notebooks
```

### Create a new simulation

```python
json_data = {
    'format': 'JSON',
    'name': 'JSON Sim',
    'content': {
        'nodes': {
            'node1': {
                'cpu': 2,
                'memory': 1024,
                'storage': 10,
                'os': 'generic/ubuntu2204',
                'cpu_arch': 'x86',
            },
        },
        'oob': False,
    },
}

sim: Simulation = api.simulations.import_from_data(**json_data)
sim.wait_for_state(SimState.INACTIVE, error_states=SimState.INVALID)
```

### Start the simulation

Request that the simulation be started. If successful, the simulation will transition from `INACTIVE` → `REQUESTING` → `PROVISIONING` → `PREPARE_BOOT` → `BOOTING` → `ACTIVE`.

```python
sim.start()
sim.wait_for_state(SimState.ACTIVE, error_states=SimState.INACTIVE)

sim.state
```

```
'ACTIVE'
```

### Shut down the simulation

Request that the simulation be shut down. Unless you specifically pass `create_checkpoint=False`, Air will default to saving a new checkpoint while shutting down. If successful, the simulation will transition from `ACTIVE` → `PREPARE_SHUTDOWN` → `SHUTTING_DOWN` → `SAVING` → `INACTIVE`.

```python
sim.shutdown()
sim.wait_for_state(SimState.INACTIVE)

for history in list(sim.get_history()):
    print(history.description)
```

```
Transitioning from `SAVING` to `INACTIVE` state.
Checkpoint `Checkpoint 2026-03-11 18:36:14` has been successfully saved.
Transitioning from `SHUTTING_DOWN` to `SAVING` state.
Simulation `JSON Sim` with ID `c0b5e717-9bd1-46dd-84c3-fdd323b32cb2` created by importing a topology in `JSON` format. Topology is scheduled for validation.
Initiating topology validation.
Validation complete. Initiating creation of simulation objects.
Topology successfully imported.
Transitioning from `IMPORTING` to `INACTIVE` state.
Transitioning from `INACTIVE` to `REQUESTING` state.
Transitioning from `REQUESTING` to `PROVISIONING` state.
Transitioning from `PROVISIONING` to `PREPARE_BOOT` state.
Transitioning from `PREPARE_BOOT` to `BOOTING` state.
Transitioning from `BOOTING` to `ACTIVE` state.
Transitioning from `ACTIVE` to `PREPARE_SHUTDOWN` state.
Transitioning from `PREPARE_SHUTDOWN` to `SHUTTING_DOWN` state.
Transitioning from `SHUTTING_DOWN` to `INACTIVE` state.
```

### Shut down the simulation without a checkpoint

Pass `create_checkpoint=False` when you request shutdown to not create a new checkpoint. The simulation will then transition from `ACTIVE` -> `PREPARE_PURGE` -> `PURGING` -> `INACTIVE`.

```python
sim.shutdown(create_checkpoint=False)
sim.wait_for_state(SimState.INACTIVE)

for history in list(sim.get_history()):
    print(history.description)
```

```
Transitioning from `PURGING` to `INACTIVE` state.
Transitioning from `PREPARE_PURGE` to `PURGING` state.
Transitioning from `ACTIVE` to `PREPARE_PURGE` state.
Purge shutdown requested; the simulation will be purged and no checkpoint will be created.
Transitioning from `BOOTING` to `ACTIVE` state.
The simulation has successfully booted. Starting billing. Putting the simulation in an `ACTIVE` state.
Transitioning from `PREPARE_BOOT` to `BOOTING` state.
Transitioning from `PROVISIONING` to `PREPARE_BOOT` state.
Transitioning from `REQUESTING` to `PROVISIONING` state.
Transitioning from `INACTIVE` to `REQUESTING` state.
Boot requested without a checkpoint.
Transitioning from `IMPORTING` to `INACTIVE` state.
Topology successfully imported.
Validation complete. Initiating creation of simulation objects.
Initiating topology validation.
Simulation `JSON Sim` with ID `c0b5e717-9bd1-46dd-84c3-fdd323b32cb2` created by importing a topology in `JSON` format. Topology is scheduled for validation.
```

```python
sim.state
```

```
'INACTIVE'
```

## Checkpoints

When a shutdown creates a checkpoint, Air persists the simulation state so you can restore later. Use `sim.checkpoints` to list, update metadata, rebuild the simulation from a snapshot, or delete a checkpoint you no longer need.

### List checkpoints

Iterate `sim.checkpoints.list()`. You can optionally filter, e.g. `state='COMPLETE'`.

```python
for cp in sim.checkpoints.list():
    print(f'{cp.name} (id={cp.id}) — state: {cp.state}')
```

```
Checkpoint 2025-09-24 18:44:55 (id=1d92e7b4-5f3a-4c81-9a2d-7b30f84c129e) — state: COMPLETE
Checkpoint 2025-09-24 18:44:55 (id=6af3c018-9b42-4f75-8d6e-1c9a3e507bd4) — state: DELETED
Checkpoint Renamed (id=e3b7a520-2149-4a6c-b8f3-0d57c9a41e86) — state: COMPLETE
```

You can optionally filter, e.g. `state='COMPLETE'`.

```python
complete = list(sim.checkpoints.list(state='COMPLETE'))
print(f'Complete checkpoints: {len(complete)}')
```

```
Complete checkpoints: 2
```

### Update a checkpoint

Rename a checkpoint or toggle `favorite` with `update()` on the checkpoint object.

`favorite` tells Air to prefer keeping this checkpoint if it ever has to automatically delete older ones to stay within your org’s checkpoint limit.

```python
cp = sim.checkpoints.get('checkpoint-id')
cp.update(name='Updated snapshot', favorite=True)
print(f'Checkpoint id: {cp.id}')
print(f'Name: {cp.name}')
print(f'Favorite: {cp.favorite}')
```

```
Checkpoint id: 1d92e7b4-5f3a-4c81-9a2d-7b30f84c129e
Name: Updated snapshot
Favorite: True
```

### Rebuild the simulation

With the simulation ACTIVE, `rebuild()` tears down and recreate its nodes. Wait until `ACTIVE` again so the rebuild finishes.

```python
if sim.state != 'ACTIVE':
    sim.start()
    sim.wait_for_state(SimState.ACTIVE, error_states=SimState.INACTIVE)

sim.rebuild()
sim.wait_for_state(SimState.ACTIVE)
print(f'Rebuild finished; simulation state: {sim.state}')
```

```
Rebuild finished; simulation state: ACTIVE
```

### Rebuild from a specific checkpoint

If you pass a checkpoint into `rebuild()`, Air rebuilds the nodes and restores them from that checkpoint’s saved state.

```python
if sim.state != 'ACTIVE':
    sim.start()
    sim.wait_for_state(SimState.ACTIVE, error_states=SimState.INACTIVE)

cp = sim.checkpoints.get('checkpoint-id')  # pick a checkpoint; adjust as needed
sim.rebuild(checkpoint=cp.id)
sim.wait_for_state(SimState.ACTIVE)
print(f'Rebuilt from checkpoint: {cp.name} (id={cp.id})')
print(f'Simulation state: {sim.state}')
```

```
Rebuilt from checkpoint: Checkpoint 2026-04-29 18:31:03 (id=6af3c018-9b42-4f75-8d6e-1c9a3e507bd4)
Simulation state: ACTIVE
```

### Delete a checkpoint

```python
cp_to_remove = sim.checkpoints.get('checkpoint-id')
cp_to_remove.delete()
```