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

# Snapshots

> Save a running sandbox and launch many sandboxes from it.

A snapshot saves the disk of a running sandbox. New sandboxes of the same Agent can launch from it, which is faster than setting each one up from scratch. A common pattern is to install your tools in one sandbox, snapshot it, then launch many sandboxes from the snapshot.

## Create a snapshot and launch from it

```python Python theme={null}
snapshot = sandbox.create_snapshot(name="base")
snapshot.wait_until_ready(timeout=600)

clone = agent.launch(snapshot_id=snapshot.id)
clone.wait_until_running()
```

```go Go theme={null}
snapshot, err := sandbox.CreateSnapshot(ctx, agentbox.CreateSnapshotParams{Name: "base"})
err = snapshot.WaitUntilReady(ctx, agentbox.WaitUntilReadyParams{Timeout: 10 * time.Minute})

clone, err := agent.Launch(ctx, agentbox.LaunchParams{SnapshotID: snapshot.ID()})
err = clone.WaitUntilRunning(ctx, agentbox.WaitUntilRunningParams{})
```

* Only a `running` sandbox can be saved. A paused sandbox returns HTTP 409; resume it first.
* Creation is asynchronous. The snapshot starts as `creating` and becomes `ready`. Wait for `ready` before you launch from it.
* If you omit the name, one is generated from the sandbox name and the time. Names are at most 255 characters.
* A sandbox launched from a snapshot uses the snapshot's size and data center. Any `instance_type` you pass is ignored.
* The source sandbox keeps running.

Waiting for `ready` raises `SnapshotFailed` (Go: `*agentbox.SnapshotFailed`) if the status becomes `error`, `deleting` or `delete_failed`, and `SnapshotWaitTimeout` if the timeout passes first.

## What a snapshot contains

* The sandbox's files on disk at the moment of the snapshot.
* Not memory or running processes. A sandbox launched from a snapshot starts fresh from the saved disk.
* Not environment variables passed with `"secret": true` at launch. Pass them again on each launch.

> [!TIP]
>
> Before you take a snapshot, remove agent configuration, login state and caches that should not be copied into every new sandbox.

## Manage snapshots

```python Python theme={null}
snapshots = agent.list_snapshots()  # newest first
snapshot.rename("base-v2")          # only when ready or error
snapshot.delete()                   # asynchronous; status becomes deleting
```

```go Go theme={null}
snapshots, err := agent.ListSnapshots(ctx) // newest first
err = snapshot.Rename(ctx, "base-v2")      // only when ready or error
err = snapshot.Delete(ctx)                 // asynchronous; status becomes deleting
```

* Snapshot statuses: `creating`, `ready`, `error`, `deleting`, `delete_failed`.
* A deleted snapshot shows `deleting` until deletion finishes, then disappears from the list. If it shows `delete_failed`, call delete again.
* Once deletion is accepted, no new sandbox can launch from the snapshot.
* Creating, renaming and deleting a snapshot require you to be its creator (or the source sandbox's creator) or an organization owner. Otherwise the call returns HTTP 403. Every organization member can list snapshots.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.