morphcloud 0.1.109__tar.gz → 0.1.111__tar.gz

{morphcloud-0.1.109 → morphcloud-0.1.111}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphcloud
-Version: 0.1.109
+Version: 0.1.111
 Summary: A Python SDK and CLI tool for creating, managing, and interacting with Morph Cloud VMs.
 Author-email: Morph Labs <jobs@morph.so>
 License: Apache-2.0
@@ -133,7 +133,7 @@ morphcloud image list [--json]
 morphcloud snapshot list [--json] [--metadata KEY=VALUE]
 
 # Create a new snapshot
-morphcloud snapshot create --image-id <id> --vcpus <n> --memory <mb> --disk-size <mb> [--digest <hash>] [--metadata KEY=VALUE]
+morphcloud snapshot create --image-id <id> --vcpus <n> --memory <mb> --disk-size <mb> [--digest <hash>] [--ttl-seconds <seconds>] [--metadata KEY=VALUE]
 
 # Get detailed snapshot information
 morphcloud snapshot get <snapshot-id>
@@ -143,6 +143,9 @@ morphcloud snapshot delete <snapshot-id>
 
 # Set metadata on a snapshot
 morphcloud snapshot set-metadata <snapshot-id> KEY1=VALUE1 [KEY2=VALUE2...]
+
+# Set or clear snapshot retention
+morphcloud snapshot set-ttl <snapshot-id> --ttl-seconds <seconds|-1>
 ```
 
 ### Instances
@@ -170,7 +173,7 @@ morphcloud instance stop <instance-id>
 morphcloud instance get <instance-id>
 
 # Create snapshot from instance
-morphcloud instance snapshot <instance-id> [--digest <hash>] [--json]
+morphcloud instance snapshot <instance-id> [--digest <hash>] [--ttl-seconds <seconds>] [--json]
 
 # Create multiple instances from an instance (branching)
 morphcloud instance branch <instance-id> [--count <n>] [--json]
@@ -213,6 +216,61 @@ morphcloud instance copy inst_123:/remote/file.log ./local_dir/
 morphcloud instance copy -r ./local_dir inst_123:/remote/dir
 ```
 
+### Volumes
+
+Morph Volumes exposes an S3-compatible object store. Bucket lifecycle and object operations use your normal `MORPH_API_KEY`.
+
+```python
+import os
+
+from morphcloud import MorphCloudClient
+
+client = MorphCloudClient(
+    api_key=os.environ["MORPH_API_KEY"],
+)
+
+client.volumes.create_bucket("my-volume-bucket")
+client.volumes.put_object(
+    "my-volume-bucket",
+    "builds/artifact.txt",
+    b"hello from morph volumes\n",
+    content_type="text/plain",
+)
+payload = client.volumes.get_object("my-volume-bucket", "builds/artifact.txt")
+client.volumes.delete_object("my-volume-bucket", "builds/artifact.txt")
+client.volumes.delete_bucket("my-volume-bucket")
+```
+
+```bash
+# List buckets
+morphcloud volumes ls
+
+# Create or remove a bucket
+morphcloud volumes mb my-volume-bucket
+morphcloud volumes rb my-volume-bucket
+
+# Browse a bucket or prefix
+morphcloud volumes ls s3://my-volume-bucket/
+morphcloud volumes tree s3://my-volume-bucket/project/
+
+# Upload, inspect, and download objects
+morphcloud volumes cp ./artifact.txt s3://my-volume-bucket/builds/artifact.txt
+morphcloud volumes cp -r ./dataset s3://my-volume-bucket/datasets/
+morphcloud volumes cat s3://my-volume-bucket/builds/artifact.txt
+morphcloud volumes cp s3://my-volume-bucket/builds/artifact.txt ./downloads/
+
+# Remove objects under a prefix
+morphcloud volumes rm -r s3://my-volume-bucket/datasets/
+```
+
+If you use profiles with non-default endpoints, the volumes gateway can be configured explicitly:
+
+```bash
+morphcloud profile set prod \
+  --api-host cloud.morph.so \
+  --volumes-base-url https://volumes.svc.cloud.morph.so
+```
+
 ### Interactive Tools
 
 ```bash
@@ -396,6 +454,48 @@ instance.stop()
 print("done\n")
 ```
 
+### Snapshot TTL
+
+`ttl_seconds` must be greater than zero when you set it. Use `None` in Python or `--ttl-seconds -1` in the CLI to remove an existing snapshot TTL.
+
+```python
+from morphcloud.api import MorphCloudClient
+
+client = MorphCloudClient()
+
+snapshot = client.snapshots.create(
+    image_id="morphvm-minimal",
+    vcpus=1,
+    memory=512,
+    disk_size=1024,
+    ttl_seconds=3600,  # auto-delete after 1 hour of inactivity
+)
+
+print(snapshot.ttl.ttl_seconds)
+print(snapshot.ttl.ttl_expire_at)
+
+# Update an existing snapshot TTL
+snapshot.set_ttl(7200)
+
+# Clear the snapshot TTL entirely
+snapshot.set_ttl(None)
+```
+
+CLI equivalents:
+
+```bash
+morphcloud snapshot create \
+  --image-id morphvm-minimal \
+  --vcpus 1 \
+  --memory 512 \
+  --disk-size 1024 \
+  --ttl-seconds 3600
+
+morphcloud snapshot set-ttl snapshot_123 --ttl-seconds 7200
+morphcloud snapshot set-ttl snapshot_123 --ttl-seconds -1
+morphcloud instance snapshot instance_123 --ttl-seconds 3600
+```
+
 ### Working with SSH
 
 ```python

{morphcloud-0.1.109 → morphcloud-0.1.111}/README.md

@@ -102,7 +102,7 @@ morphcloud image list [--json]
 morphcloud snapshot list [--json] [--metadata KEY=VALUE]
 
 # Create a new snapshot
-morphcloud snapshot create --image-id <id> --vcpus <n> --memory <mb> --disk-size <mb> [--digest <hash>] [--metadata KEY=VALUE]
+morphcloud snapshot create --image-id <id> --vcpus <n> --memory <mb> --disk-size <mb> [--digest <hash>] [--ttl-seconds <seconds>] [--metadata KEY=VALUE]
 
 # Get detailed snapshot information
 morphcloud snapshot get <snapshot-id>
@@ -112,6 +112,9 @@ morphcloud snapshot delete <snapshot-id>
 
 # Set metadata on a snapshot
 morphcloud snapshot set-metadata <snapshot-id> KEY1=VALUE1 [KEY2=VALUE2...]
+
+# Set or clear snapshot retention
+morphcloud snapshot set-ttl <snapshot-id> --ttl-seconds <seconds|-1>
 ```
 
 ### Instances
@@ -139,7 +142,7 @@ morphcloud instance stop <instance-id>
 morphcloud instance get <instance-id>
 
 # Create snapshot from instance
-morphcloud instance snapshot <instance-id> [--digest <hash>] [--json]
+morphcloud instance snapshot <instance-id> [--digest <hash>] [--ttl-seconds <seconds>] [--json]
 
 # Create multiple instances from an instance (branching)
 morphcloud instance branch <instance-id> [--count <n>] [--json]
@@ -182,6 +185,61 @@ morphcloud instance copy inst_123:/remote/file.log ./local_dir/
 morphcloud instance copy -r ./local_dir inst_123:/remote/dir
 ```
 
+### Volumes
+
+Morph Volumes exposes an S3-compatible object store. Bucket lifecycle and object operations use your normal `MORPH_API_KEY`.
+
+```python
+import os
+
+from morphcloud import MorphCloudClient
+
+client = MorphCloudClient(
+    api_key=os.environ["MORPH_API_KEY"],
+)
+
+client.volumes.create_bucket("my-volume-bucket")
+client.volumes.put_object(
+    "my-volume-bucket",
+    "builds/artifact.txt",
+    b"hello from morph volumes\n",
+    content_type="text/plain",
+)
+payload = client.volumes.get_object("my-volume-bucket", "builds/artifact.txt")
+client.volumes.delete_object("my-volume-bucket", "builds/artifact.txt")
+client.volumes.delete_bucket("my-volume-bucket")
+```
+
+```bash
+# List buckets
+morphcloud volumes ls
+
+# Create or remove a bucket
+morphcloud volumes mb my-volume-bucket
+morphcloud volumes rb my-volume-bucket
+
+# Browse a bucket or prefix
+morphcloud volumes ls s3://my-volume-bucket/
+morphcloud volumes tree s3://my-volume-bucket/project/
+
+# Upload, inspect, and download objects
+morphcloud volumes cp ./artifact.txt s3://my-volume-bucket/builds/artifact.txt
+morphcloud volumes cp -r ./dataset s3://my-volume-bucket/datasets/
+morphcloud volumes cat s3://my-volume-bucket/builds/artifact.txt
+morphcloud volumes cp s3://my-volume-bucket/builds/artifact.txt ./downloads/
+
+# Remove objects under a prefix
+morphcloud volumes rm -r s3://my-volume-bucket/datasets/
+```
+
+If you use profiles with non-default endpoints, the volumes gateway can be configured explicitly:
+
+```bash
+morphcloud profile set prod \
+  --api-host cloud.morph.so \
+  --volumes-base-url https://volumes.svc.cloud.morph.so
+```
+
 ### Interactive Tools
 
 ```bash
@@ -365,6 +423,48 @@ instance.stop()
 print("done\n")
 ```
 
+### Snapshot TTL
+
+`ttl_seconds` must be greater than zero when you set it. Use `None` in Python or `--ttl-seconds -1` in the CLI to remove an existing snapshot TTL.
+
+```python
+from morphcloud.api import MorphCloudClient
+
+client = MorphCloudClient()
+
+snapshot = client.snapshots.create(
+    image_id="morphvm-minimal",
+    vcpus=1,
+    memory=512,
+    disk_size=1024,
+    ttl_seconds=3600,  # auto-delete after 1 hour of inactivity
+)
+
+print(snapshot.ttl.ttl_seconds)
+print(snapshot.ttl.ttl_expire_at)
+
+# Update an existing snapshot TTL
+snapshot.set_ttl(7200)
+
+# Clear the snapshot TTL entirely
+snapshot.set_ttl(None)
+```
+
+CLI equivalents:
+
+```bash
+morphcloud snapshot create \
+  --image-id morphvm-minimal \
+  --vcpus 1 \
+  --memory 512 \
+  --disk-size 1024 \
+  --ttl-seconds 3600
+
+morphcloud snapshot set-ttl snapshot_123 --ttl-seconds 7200
+morphcloud snapshot set-ttl snapshot_123 --ttl-seconds -1
+morphcloud instance snapshot instance_123 --ttl-seconds 3600
+```
+
 ### Working with SSH
 
 ```python

{morphcloud-0.1.109 → morphcloud-0.1.111}/morphcloud/api.py

@@ -24,6 +24,7 @@ from morphcloud.config import resolve_settings
 
 if typing.TYPE_CHECKING:
     from morphcloud.devbox.client import AsyncDevboxClient, DevboxClient
+    from morphcloud.volumes.client import VolumesClient
 
 # Global console instance
 console = Console()
@@ -109,6 +110,29 @@ class TTL(BaseModel):
     )
 
 
+class SnapshotTTL(BaseModel):
+    """Represents the retention policy for a snapshot."""
+
+    ttl_seconds: typing.Optional[int] = Field(
+        None, description="Time in seconds until the snapshot expires."
+    )
+    ttl_expire_at: typing.Optional[int] = Field(
+        None, description="Unix timestamp when the snapshot is set to expire."
+    )
+
+
+def _validate_snapshot_ttl_seconds(
+    ttl_seconds: typing.Optional[int], *, allow_none: bool
+) -> None:
+    """Validate snapshot TTL values before sending them to the API."""
+    if ttl_seconds is None:
+        if allow_none:
+            return
+        raise ValueError("ttl_seconds must be greater than zero")
+    if ttl_seconds <= 0:
+        raise ValueError("ttl_seconds must be greater than zero")
+
+
 class WakeOn(BaseModel):
     """Represents the wake-on-event configuration for an instance."""
 
@@ -139,6 +163,8 @@ class MorphCloudClient:
         profile: typing.Optional[str] = None,
         api_host: typing.Optional[str] = None,
         service_base_url: typing.Optional[str] = None,
+        volumes_base_url: typing.Optional[str] = None,
+        volumes_service_api_key: typing.Optional[str] = None,
         admin_base_url: typing.Optional[str] = None,
         db_base_url: typing.Optional[str] = None,
         ssh_hostname: typing.Optional[str] = None,
@@ -152,6 +178,7 @@ class MorphCloudClient:
                 "base_url": base_url,
                 "api_host": api_host,
                 "service_base_url": service_base_url,
+                "volumes_base_url": volumes_base_url,
                 "devbox_base_url": devbox_base_url,
                 "admin_base_url": admin_base_url,
                 "db_base_url": db_base_url,
@@ -166,12 +193,17 @@ class MorphCloudClient:
         self.ssh_hostname = settings.ssh_hostname
         self.ssh_port = settings.ssh_port
         self.service_base_url = settings.service_base_url
+        self.volumes_base_url = settings.volumes_base_url
+        self.volumes_service_api_key = volumes_service_api_key or os.environ.get(
+            "MORPH_VOLUMES_SERVICE_API_KEY"
+        )
         self.devbox_base_url = settings.devbox_base_url
         self.admin_base_url = settings.admin_base_url
         self.db_base_url = settings.db_base_url
         self.profile = settings.profile
         self._devbox_client = None
         self._devbox_async_client = None
+        self._volumes_client = None
         if not self.api_key:
             raise ValueError(
                 "API key must be provided or set in MORPH_API_KEY environment variable"
@@ -295,6 +327,18 @@ class MorphCloudClient:
         """Access the API for the current authenticated user."""
         return UserAPI(self)
 
+    @property
+    def volumes(self) -> "VolumesClient":
+        if self._volumes_client is None:
+            from morphcloud.volumes.client import VolumesClient
+
+            self._volumes_client = VolumesClient(self)
+        return self._volumes_client
+
+    @volumes.setter
+    def volumes(self, value: "VolumesClient") -> None:
+        self._volumes_client = value
+
 
 class BaseAPI:
     def __init__(self, client: MorphCloudClient):
@@ -645,6 +689,7 @@ class SnapshotAPI:
         disk_size: typing.Optional[int] = None,
         digest: typing.Optional[str] = None,
         metadata: typing.Optional[typing.Dict[str, str]] = None,
+        ttl_seconds: typing.Optional[int] = None,
     ) -> Snapshot:
         """Create a new snapshot from a base image and a machine configuration.
 
@@ -654,7 +699,11 @@ class SnapshotAPI:
             memory: The amount of memory (in MB) for the snapshot.
             disk_size: The size of the snapshot (in MB).
             digest: Optional digest for the snapshot. If provided, it will be used to identify the snapshot. If a snapshot with the same digest already exists, it will be returned instead of creating a new one.
-            metadata: Optional metadata to attach to the snapshot."""
+            metadata: Optional metadata to attach to the snapshot.
+            ttl_seconds: Optional retention period in seconds before the snapshot is automatically deleted.
+        """
+        if ttl_seconds is not None:
+            _validate_snapshot_ttl_seconds(ttl_seconds, allow_none=False)
         body = {}
         if image_id is not None:
             body["image_id"] = image_id
@@ -668,6 +717,8 @@ class SnapshotAPI:
             body["digest"] = digest
         if metadata is not None:
             body["metadata"] = metadata
+        if ttl_seconds is not None:
+            body["ttl_seconds"] = ttl_seconds
         response = self._client._http_client.post("/snapshot", json=body)
         snap: Snapshot = Snapshot.model_validate(response.json())._set_api(self)
         snap.wait_until_ready()
@@ -681,6 +732,7 @@ class SnapshotAPI:
         disk_size: typing.Optional[int] = None,
         digest: typing.Optional[str] = None,
         metadata: typing.Optional[typing.Dict[str, str]] = None,
+        ttl_seconds: typing.Optional[int] = None,
     ) -> Snapshot:
         """Create a new snapshot from a base image and a machine configuration.
 
@@ -690,7 +742,11 @@ class SnapshotAPI:
             memory: The amount of memory (in MB) for the snapshot.
             disk_size: The size of the snapshot (in MB).
             digest: Optional digest for the snapshot. If provided, it will be used to identify the snapshot. If a snapshot with the same digest already exists, it will be returned instead of creating a new one.
-            metadata: Optional metadata to attach to the snapshot."""
+            metadata: Optional metadata to attach to the snapshot.
+            ttl_seconds: Optional retention period in seconds before the snapshot is automatically deleted.
+        """
+        if ttl_seconds is not None:
+            _validate_snapshot_ttl_seconds(ttl_seconds, allow_none=False)
         body = {}
         if image_id is not None:
             body["image_id"] = image_id
@@ -704,6 +760,8 @@ class SnapshotAPI:
             body["digest"] = digest
         if metadata is not None:
             body["metadata"] = metadata
+        if ttl_seconds is not None:
+            body["ttl_seconds"] = ttl_seconds
         response = await self._client._async_http_client.post("/snapshot", json=body)
         snap: Snapshot = Snapshot.model_validate(response.json())._set_api(self)
         await snap.await_until_ready()
@@ -735,6 +793,7 @@ class Snapshot(BaseModel):
     metadata: typing.Dict[str, str] = Field(
         default_factory=dict, description="User provided metadata"
     )
+    ttl: SnapshotTTL = Field(default_factory=SnapshotTTL)
 
     _api: SnapshotAPI = PrivateAttr()
 
@@ -771,6 +830,28 @@ class Snapshot(BaseModel):
         response.raise_for_status()
         await self._refresh_async()
 
+    def set_ttl(self, ttl_seconds: typing.Optional[int]) -> None:
+        """Set or clear the retention policy for this snapshot.
+
+        Parameters:
+            ttl_seconds: New TTL in seconds. Pass None to remove the snapshot TTL.
+        """
+        _validate_snapshot_ttl_seconds(ttl_seconds, allow_none=True)
+        response = self._api._client._http_client.post(
+            f"/snapshot/{self.id}/ttl", json={"ttl_seconds": ttl_seconds}
+        )
+        response.raise_for_status()
+        self._refresh()
+
+    async def aset_ttl(self, ttl_seconds: typing.Optional[int]) -> None:
+        """Async version of set_ttl()."""
+        _validate_snapshot_ttl_seconds(ttl_seconds, allow_none=True)
+        response = await self._api._client._async_http_client.post(
+            f"/snapshot/{self.id}/ttl", json={"ttl_seconds": ttl_seconds}
+        )
+        response.raise_for_status()
+        await self._refresh_async()
+
     def _refresh(self) -> None:
         refreshed = self._api.get(self.id)
         updated = type(self).model_validate(refreshed.model_dump())
@@ -2769,13 +2850,27 @@ class Instance(BaseModel):
         self,
         digest: typing.Optional[str] = None,
         metadata: typing.Optional[typing.Dict[str, str]] = None,
+        ttl_seconds: typing.Optional[int] = None,
     ) -> Snapshot:
-        """Save the instance as a snapshot."""
+        """Save the instance as a snapshot.
+
+        Parameters:
+            digest: Optional digest to associate with the new snapshot.
+            metadata: Optional metadata to attach to the new snapshot.
+            ttl_seconds: Optional retention period in seconds before the snapshot is automatically deleted.
+        """
+        if ttl_seconds is not None:
+            _validate_snapshot_ttl_seconds(ttl_seconds, allow_none=False)
         params = {}
         if digest is not None:
             params["digest"] = digest
+        body: typing.Dict[str, typing.Any] = {}
+        if metadata is not None:
+            body["metadata"] = metadata
+        if ttl_seconds is not None:
+            body["ttl_seconds"] = ttl_seconds
         response = self._api._client._http_client.post(
-            f"/instance/{self.id}/snapshot", params=params, json=dict(metadata=metadata)
+            f"/instance/{self.id}/snapshot", params=params, json=body
         )
         return Snapshot.model_validate(response.json())._set_api(
             self._api._client.snapshots,
@@ -2785,13 +2880,21 @@ class Instance(BaseModel):
         self,
         digest: typing.Optional[str] = None,
         metadata: typing.Optional[typing.Dict[str, str]] = None,
+        ttl_seconds: typing.Optional[int] = None,
     ) -> Snapshot:
-        """Save the instance as a snapshot."""
+        """Async version of snapshot()."""
+        if ttl_seconds is not None:
+            _validate_snapshot_ttl_seconds(ttl_seconds, allow_none=False)
         params = {}
         if digest is not None:
             params = {"digest": digest}
+        body: typing.Dict[str, typing.Any] = {}
+        if metadata is not None:
+            body["metadata"] = metadata
+        if ttl_seconds is not None:
+            body["ttl_seconds"] = ttl_seconds
         response = await self._api._client._async_http_client.post(
-            f"/instance/{self.id}/snapshot", params=params, json=dict(metadata=metadata)
+            f"/instance/{self.id}/snapshot", params=params, json=body
         )
         return Snapshot.model_validate(response.json())._set_api(
             self._api._client.snapshots