Skip to main content

Snapshot TTL

Snapshot TTL sets a retention window on saved snapshots. It is different from instance TTL: snapshot TTL governs stored snapshot state and automatic cleanup, not whether a running VM pauses or stops.

Each snapshot can carry:

  • ttl_seconds: the retention period in seconds
  • ttl_expire_at: the Unix timestamp when the snapshot is currently scheduled to expire

When you set ttl_seconds, it must be greater than zero. To clear snapshot TTL, send null in the API or use the dedicated clear path shown below.

Snapshot TTL is based on the snapshot's last-used timestamp, with creation time as the initial baseline. In practice, that means actively reused snapshots can get a later ttl_expire_at, while dormant snapshots age out. When a snapshot expires, the platform marks it for deletion and reclaims it asynchronously.

Generated REST API reference may lag this feature

If the generated /api-reference pages do not yet show snapshot TTL request or response fields, use the examples on this page. The deployed API already accepts and returns snapshot TTL data even when the public OpenAPI snapshot has not caught up yet.

Create a Snapshot with TTL​

Use ttl_seconds at creation time when you already know a snapshot is disposable, such as a build cache, one-off checkpoint, or temporary warm-start image.

from morphcloud.api import MorphCloudClient

client = MorphCloudClient()

snapshot = client.snapshots.create(
    image_id="morphvm-minimal",
    vcpus=2,
    memory=4096,
    disk_size=50000,
    ttl_seconds=3600,  # 1 hour
)

print(snapshot.id)
print(snapshot.ttl.ttl_seconds)
print(snapshot.ttl.ttl_expire_at)

Save a Running Instance with TTL​

You can also attach retention when checkpointing a running instance. The instance must be in the READY state when you create the snapshot.

from morphcloud.api import MorphCloudClient

client = MorphCloudClient()

instance = client.instances.get("instance_your_instance_id")
snapshot = instance.snapshot(
    ttl_seconds=3600,
    metadata={"purpose": "temp-checkpoint"},
)

print(snapshot.id)
print(snapshot.ttl.ttl_expire_at)

Inspect Snapshot TTL​

Read the snapshot object back when you need the current retention state or computed expiration timestamp.

from morphcloud.api import MorphCloudClient

client = MorphCloudClient()

snapshot = client.snapshots.get("snapshot_your_snapshot_id")

print(snapshot.ttl.ttl_seconds)
print(snapshot.ttl.ttl_expire_at)

Update or Clear Snapshot TTL​

You can extend retention, shorten it, or remove it entirely on an existing snapshot.

from morphcloud.api import MorphCloudClient

client = MorphCloudClient()

snapshot = client.snapshots.get("snapshot_your_snapshot_id")

# Extend retention to 2 hours
snapshot.set_ttl(7200)

# Remove the retention policy entirely
snapshot.set_ttl(None)

Best Practices​

  • Use snapshot TTL for disposable caches, temporary checkpoints, and short-lived warm-start images.
  • Leave TTL unset for canonical golden snapshots that are meant to stay around until you explicitly delete them.
  • Read back the snapshot after creating or updating TTL if you need the exact computed ttl_expire_at value.
  • Use instance TTL when your goal is controlling running compute lifetime rather than stored snapshot lifetime.