diff --git a/src/langsmith/sandbox-cli.mdx b/src/langsmith/sandbox-cli.mdx
index 4ef43088fb..e2f47ba3d3 100644
--- a/src/langsmith/sandbox-cli.mdx
+++ b/src/langsmith/sandbox-cli.mdx
@@ -58,14 +58,12 @@ langsmith sandbox snapshot build my-snapshot \
   --wait
 ```
 
-For private registries, pass registry credentials from environment variables:
+For private images, create a registry first (see [Private registries](/langsmith/sandbox-snapshots#private-registries)), then pass its id with `--registry-id`:
 
 ```bash
 langsmith sandbox snapshot build internal-python \
   --docker-image registry.example.com/internal/python:3.12 \
-  --registry-url https://registry.example.com \
-  --registry-username "$REGISTRY_USERNAME" \
-  --registry-password "$REGISTRY_PASSWORD" \
+  --registry-id "$REGISTRY_ID" \
   --wait
 ```
 
diff --git a/src/langsmith/sandbox-snapshots.mdx b/src/langsmith/sandbox-snapshots.mdx
index 2a777274c1..3a115dac55 100644
--- a/src/langsmith/sandbox-snapshots.mdx
+++ b/src/langsmith/sandbox-snapshots.mdx
@@ -48,33 +48,43 @@ console.log(snapshot.id);
 
 ### Private registries
 
-Pass registry credentials (or a pre-registered `registry_id` / `registryId`) to pull from a private registry.
+To pull from a private registry, create a registry once with its credentials, then reference it by id when building a snapshot. Registries persist, so reuse one across snapshots.
 
 <CodeGroup>
 
 ```python Python
 import os
 
+registry = client.registries.create(
+    name="internal",
+    url="registry.example.com",
+    username="me",
+    password=os.environ["REGISTRY_PASSWORD"],
+)
+
 snapshot = client.create_snapshot(
     "internal-python",
     docker_image="registry.example.com/internal/python:3.12",
     fs_capacity_bytes=2 * 1024**3,
-    registry_url="https://registry.example.com",
-    registry_username="me",
-    registry_password=os.environ["REGISTRY_PASSWORD"],
+    registry_id=registry.id,
     timeout=600,
 )
 ```
 
 ```ts TypeScript
+const registry = await client.registries.create({
+  name: "internal",
+  url: "registry.example.com",
+  username: "me",
+  password: process.env.REGISTRY_PASSWORD,
+});
+
 const snapshot = await client.createSnapshot(
   "internal-python",
   "registry.example.com/internal/python:3.12",
   2_147_483_648,
   {
-    registryUrl: "https://registry.example.com",
-    registryUsername: "me",
-    registryPassword: process.env.REGISTRY_PASSWORD,
+    registryId: registry.id,
     timeout: 600,
   },
 );
@@ -82,6 +92,8 @@ const snapshot = await client.createSnapshot(
 
 </CodeGroup>
 
+List, inspect, update, and delete registries with `client.registries.list()`, `client.registries.retrieve(name)`, `client.registries.update(name, ...)`, and `client.registries.delete(name)`.
+
 ## Build a snapshot from a Dockerfile
 
 When you have a local `Dockerfile` but don't want to publish the image to a registry first, build a snapshot directly from the `Dockerfile` and its build context. LangSmith spins up a temporary builder sandbox, uploads the context, runs the build inside it with [BuildKit](https://docs.docker.com/build/buildkit/), and captures the resulting image as a snapshot. The builder sandbox is torn down automatically once the build finishes.