From f81e8860164cf841f1180ae5046c02627c83c481 Mon Sep 17 00:00:00 2001 From: jasonkeung Date: Wed, 27 May 2026 16:59:05 -0400 Subject: [PATCH 1/3] Clarify self-hosted task images Explain that custom dependencies belong in the cloud agent task image, not the Warp-managed sidecar/runtime image, and clarify Kubernetes default_image usage. Co-Authored-By: Oz --- src/content/docs/agent-platform/cloud-agents/environments.mdx | 4 +++- .../docs/agent-platform/cloud-agents/self-hosting/index.mdx | 2 +- .../cloud-agents/self-hosting/managed-kubernetes.mdx | 2 +- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/environments.mdx b/src/content/docs/agent-platform/cloud-agents/environments.mdx index ee398826..717a7a6a 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 include or set up `warp-agent`; 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..c5c8a98a 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 the run has no Warp environment image. Use this image for project dependencies, system packages, and scripts. 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`. From f09d5f432c6b2aec9c8fd2989acce36c94068756 Mon Sep 17 00:00:00 2001 From: Jason Keung Date: Wed, 27 May 2026 17:41:57 -0400 Subject: [PATCH 2/3] Update src/content/docs/agent-platform/cloud-agents/environments.mdx Co-authored-by: Lili Wilson <56806227+liliwilson@users.noreply.github.com> --- src/content/docs/agent-platform/cloud-agents/environments.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/agent-platform/cloud-agents/environments.mdx b/src/content/docs/agent-platform/cloud-agents/environments.mdx index 717a7a6a..406583c6 100644 --- a/src/content/docs/agent-platform/cloud-agents/environments.mdx +++ b/src/content/docs/agent-platform/cloud-agents/environments.mdx @@ -37,7 +37,7 @@ An environment typically includes: * **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 include or set up `warp-agent`; 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). +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: From 16234d3abbd6c90c5813cc2b686efbfb53bb1731 Mon Sep 17 00:00:00 2001 From: Jason Keung Date: Wed, 27 May 2026 17:56:04 -0400 Subject: [PATCH 3/3] Apply suggestion from @liliwilson Co-authored-by: Lili Wilson <56806227+liliwilson@users.noreply.github.com> --- .../cloud-agents/self-hosting/managed-kubernetes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 c5c8a98a..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. Use this image for project dependencies, system packages, and scripts. 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`.