> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# The Devbox Lifecycle

> Understand the stages of the Devbox lifecycle.

<Tip>Start with the [Runloop Quickstart](/docs/tutorials/quickstart) to use the examples below.</Tip>

## Devbox States

Devboxes represent a persistent dev environment that can be launched and shut down as needed.
Over the course of a Devbox's lifecycle, it will transition through a series of states depending on your use case:

* **Provisioning**: Runloop is allocating and booting the necessary infrastructure resources.
* **Initializing**: Runloop defined boot scripts are running to enable the environment for interaction.
* **Running**: The Devbox is ready for interaction.
* **Failure**: The Devbox failed as part of booting or running user requested actions.
* **Shutdown**: The Devbox was successfully shutdown and no more active compute is being used.
* **Suspending**: The Devbox disk is being snapshotted and as part of suspension.
* **Suspended**: The Devbox disk is saved and no more active compute is being used for the Devbox.
* **Resuming**: The Devbox disk is being loaded as part of booting a suspended Devbox.

<Note>
  Compute is billed only while devbox status is one of \[`initializing`, `running`, `suspending`, `resuming`].
</Note>

## <a name="suspend_resume" />Suspending and Resuming Devboxes to Save Disk State

In addition to use idle management configuration, you can also manually suspend and resume a devbox.

<Warning>
  Devboxes are by definition ephemeral
  environments. Please consistently snapshot your devboxes to maintain disk
  state for your projects.
</Warning>

<Note>Only disk state, not in-memory state is preserved during suspend/resume operations</Note>

<Steps>
  <Step title="Suspend the devbox">
    <CodeGroup>
      ```python Python theme={null}
      devbox = runloop.devbox.from_id(devbox_id)
      await devbox.suspend()
      ```

      ```typescript TypeScript theme={null}
      const devbox = runloop.devbox.fromId(devboxId);
      await devbox.suspend();
      ```
    </CodeGroup>
  </Step>

  <Step title="Wait for the devbox to be suspended">
    <CodeGroup>
      ```python Python theme={null}
      await devbox.await_suspended()
      ```

      ```typescript TypeScript theme={null}
      await devbox.awaitSuspended();
      ```
    </CodeGroup>
  </Step>

  <Step title="Resume when needed">
    <CodeGroup>
      ```python Python theme={null}
      devbox = runloop.devbox.from_id(devbox_id)
      await devbox.resume()
      ```

      ```typescript TypeScript theme={null}
      const devbox = await runloop.devbox.fromId(devboxId);
      await devbox.resume();
      ```
    </CodeGroup>
  </Step>

  <Step title="Wait for the devbox to be running">
    <CodeGroup>
      ```python Python theme={null}
      await devbox.await_running()
      ```

      ```typescript TypeScript theme={null}
      await devbox.awaitRunning();    
      ```
    </CodeGroup>
  </Step>
</Steps>

## Important Notes

* Suspended Devboxes still incur storage charges until explicitly shut down
* The suspend/resume process typically takes seconds, depending on the amount of modified data
* Daemons or other processes running at suspend time must be manually restarted after resuming
* The original Devbox ID and SSH keys are preserved through suspend/resume cycles