diff --git a/src/content/docs/agent-platform/cloud-agents/environments.mdx b/src/content/docs/agent-platform/cloud-agents/environments.mdx
index ee398826..406583c6 100644
--- a/src/content/docs/agent-platform/cloud-agents/environments.mdx
+++ b/src/content/docs/agent-platform/cloud-agents/environments.mdx
@@ -33,10 +33,12 @@ Environments define _how_ an agent runs, not _what_ it does. They're required fo
 
 An environment typically includes:
 
-* **Docker image (required)** – The toolchain and runtime the agent runs with. For self-hosted Kubernetes workers, a [`default_image`](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/) on the worker lets you skip creating an environment entirely.
+* **Docker image (required)** – The task/workspace image with the toolchain and dependencies your code needs. For self-hosted Kubernetes workers, a [`default_image`](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/) on the worker lets you skip creating an environment entirely.
 * **Repository/workspace** – One or more repos the agent can clone and operate on.
 * **Setup commands** – Commands to prepare the workspace (e.g., dependency install, builds, bootstrapping).
 
+Use the Docker image for language runtimes, package managers, system libraries, and scripts needed by your project. Custom images do not need to handle installing the Warp CLI binary; Warp supplies the agent runtime separately. You can start from an official image or one of Warp's [prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments).
+
 :::note
 Configuring runtime settings:
 
diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx
index cbb98904..ae352a60 100644
--- a/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx
+++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx
@@ -181,7 +181,7 @@ When creating a run, schedule, or integration in the [Oz web app](https://oz.war
 
 Self-hosted workers fully support [environments](/agent-platform/cloud-agents/environments/). When a task specifies an environment, the worker resolves the Docker image, clones the repositories, runs setup commands, and executes the agent inside the prepared container or Kubernetes Job.
 
-The same environment can be used for both Warp-hosted and self-hosted runs without modification. See [Environments](/agent-platform/cloud-agents/environments/) for details on creating and configuring them.
+The same environment can be used for both Warp-hosted and self-hosted runs without modification. If your agents need custom tools, binaries, scripts, or system packages, add them to the environment's Docker image. See [Environments](/agent-platform/cloud-agents/environments/) for details on creating and configuring custom images.
 
 :::note
 With the Kubernetes backend, setting a [`default_image`](/agent-platform/cloud-agents/self-hosting/reference/#kubernetes-backend-config) on the worker lets you skip creating a Warp environment when all your tasks use the same base image.
diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx
index 278c424d..4ee1abc5 100644
--- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx
+++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx
@@ -123,7 +123,7 @@ To scale horizontally, deploy multiple Helm releases with distinct worker IDs ra
 **Kubernetes backend:**
 
 * `kubernetesBackend.namespace` — Namespace for task Jobs. Defaults to the release namespace.
-* `kubernetesBackend.defaultImage` — Default Docker image for task pods when the run has no Warp environment image. Leave empty (default) to fall back to `ubuntu:22.04`.
+* `kubernetesBackend.defaultImage` — Default Docker image for task pods when no [Warp environment](/agent-platform/cloud-agents/environments/) has been supplied. Leave empty (default) to fall back to `ubuntu:22.04`.
 * `kubernetesBackend.imagePullPolicy` — Image pull policy for task pods. Defaults to `IfNotPresent`.
 * `kubernetesBackend.preflightImage` — Image for the startup preflight Job. Set this if your cluster restricts allowed registries.
 * `kubernetesBackend.unschedulableTimeout` — How long a pod may remain unschedulable before failing. Defaults to `30s`.