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.

Python

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)

CLI

morphcloud snapshot create \
  --image-id morphvm-minimal \
  --vcpus 2 \
  --memory 4096 \
  --disk-size 50000 \
  --ttl-seconds 3600

HTTP

curl -sS -X POST \
  -H "Authorization: Bearer $MORPH_API_KEY" \
  -H "Content-Type: application/json" \
  https://cloud.morph.so/api/snapshot \
  -d '{
    "image_id": "morphvm-minimal",
    "vcpus": 2,
    "memory": 4096,
    "disk_size": 50000,
    "ttl_seconds": 3600
  }' | jq '.ttl'

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.

Python

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)

CLI

morphcloud instance snapshot instance_your_instance_id \
  --ttl-seconds 3600 \
  --metadata purpose=temp-checkpoint

HTTP

curl -sS -X POST \
  -H "Authorization: Bearer $MORPH_API_KEY" \
  -H "Content-Type: application/json" \
  https://cloud.morph.so/api/instance/instance_your_instance_id/snapshot \
  -d '{
    "metadata": {"purpose": "temp-checkpoint"},
    "ttl_seconds": 3600
  }' | jq '.ttl'

Inspect Snapshot TTL

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

Python

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)

CLI

morphcloud snapshot get snapshot_your_snapshot_id | jq '.ttl'

HTTP

curl -sS \
  -H "Authorization: Bearer $MORPH_API_KEY" \
  https://cloud.morph.so/api/snapshot/snapshot_your_snapshot_id | jq '.ttl'

Update or Clear Snapshot TTL

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

Python

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)

CLI

# Set or update snapshot retention
morphcloud snapshot set-ttl snapshot_your_snapshot_id --ttl-seconds 7200

# Clear snapshot retention
morphcloud snapshot set-ttl snapshot_your_snapshot_id --ttl-seconds -1

HTTP

# Set or update snapshot retention
curl -sS -X POST \
  -H "Authorization: Bearer $MORPH_API_KEY" \
  -H "Content-Type: application/json" \
  https://cloud.morph.so/api/snapshot/snapshot_your_snapshot_id/ttl \
  -d '{"ttl_seconds": 7200}' | jq '.ttl'

# Clear snapshot retention
curl -sS -X POST \
  -H "Authorization: Bearer $MORPH_API_KEY" \
  -H "Content-Type: application/json" \
  https://cloud.morph.so/api/snapshot/snapshot_your_snapshot_id/ttl \
  -d '{"ttl_seconds": null}' | jq '.ttl'

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.