TTL (Time-to-Live)

Time-to-Live (TTL) functionality allows you to specify a duration after which an instance will automatically shut down or pause. This is useful for cost management and to avoid leaving idle instances running.

Start Instance with TTL

When starting an instance, you can specify a Time-To-Live (TTL) to set the duration in seconds before the instance expires. You can also define the action to take upon expiration using ttl_action, which can be either stop or pause.

Python

from morphcloud.api import MorphCloudClient

client = MorphCloudClient()

snapshot_id = "snapshot_your_snapshot_id" # Replace with a valid snapshot ID
instance = client.instances.start(
    snapshot_id=snapshot_id, 
    ttl_seconds=3600,  # 1 hour
    ttl_action="stop"  # Can be 'stop' or 'pause'
)

print(f"Instance started with ID: {instance.id} and TTL configured for 1 hour.")

TypeScript

import { MorphCloudClient } from 'morphcloud';

const client = new MorphCloudClient();

async function startInstanceWithTTL() {
  const snapshot_id = "snapshot_your_snapshot_id"; // Replace with a valid snapshot ID
  const instance = await client.instances.start({ 
    snapshot_id: snapshot_id, 
    ttl_seconds: 3600,  // 1 hour
    ttl_action: "stop"  // Can be 'stop' or 'pause'
  });

  console.log(`Instance started with ID: ${instance.id} and TTL configured for 1 hour.`);
}

startInstanceWithTTL();

CLI

# Start an instance with TTL
morphcloud instance start snapshot_your_snapshot_id --ttl-seconds 3600 --ttl-action stop

TTL Actions

When configuring TTL, you can specify one of two actions to happen when the TTL expires:

1. stop: The instance will be completely shut down, and all resources will be released. This is the most cost-effective option as you will no longer be charged for the instance after it stops.

2. pause: The instance will be paused, preserving its memory state. This allows you to resume the instance later with all applications in the exact state they were in. You will still be charged for storage, but not for compute resources while the instance is paused.

Setting TTL for Running Instances

You can set/update the TTL for an already running instance:

Python

from morphcloud.api import MorphCloudClient

client = MorphCloudClient()

instance_id = "instance_your_instance_id" # Replace with a valid instance ID

# Set TTL for 2 more hours
instance = client.instances.get(instance_id=instance_id)
instance.set_ttl(
    ttl_seconds=7200,  # 2 hours
    ttl_action="pause"  # Can be 'stop' or 'pause'
)

print(f"TTL set for instance '{instance_id}'")

TypeScript

import { MorphCloudClient } from 'morphcloud';

const client = new MorphCloudClient();

async function setInstanceTTL() {
  const instance_id = "instance_your_instance_id"; // Replace with a valid instance ID

  // Set TTL for 2 more hours
  const instance = await client.instances.get({ instance_id: instance_id });
  await instance.set_ttl({
    ttl_seconds: 7200,  // 2 hours
    ttl_action: "pause"  // Can be 'stop' or 'pause'
  });

  console.log(`TTL set for instance '${instance_id}'`);
}

setInstanceTTL();

CLI

# Update TTL for a running instance
morphcloud instance set-ttl instance_your_instance_id --ttl-seconds 7200 --ttl-action pause

Checking Remaining TTL

You can check the remaining TTL for an instance:

Python

from morphcloud.api import MorphCloudClient

client = MorphCloudClient()

instance_id = "instance_your_instance_id" # Replace with a valid instance ID
instance = client.instances.get(instance_id=instance_id)

ttl_info = instance.get_ttl_info()

print(f"TTL expires at: {ttl_info.expires_at}")
print(f"TTL action: {ttl_info.action}")
print(f"Seconds remaining: {ttl_info.seconds_remaining}")

TypeScript

import { MorphCloudClient } from 'morphcloud';

const client = new MorphCloudClient();

async function checkRemainingTTL() {
  const instance_id = "instance_your_instance_id"; // Replace with a valid instance ID
  const instance = await client.instances.get({ instance_id: instance_id });

  const ttlInfo = await instance.getTTLInfo();

  console.log(`TTL expires at: ${ttlInfo.expiresAt}`);
  console.log(`TTL action: ${ttlInfo.action}`);
  console.log(`Seconds remaining: ${ttlInfo.secondsRemaining}`);
}

checkRemainingTTL();

CLI

# Check TTL information for an instance
morphcloud instance get-ttl instance_your_instance_id

Best Practices for TTL

1. Use TTL for temporary workloads: Set appropriate TTLs for workloads that have a defined duration, like CI/CD jobs or development environments.

2. Choose the right action: Use stop for one-off tasks and pause for work that might need to be resumed later.

3. Set realistic durations: Avoid setting unnecessarily long TTLs; you can always extend them if needed.

4. Monitor expiration: Build processes to monitor TTL expirations and take action if needed.