From 4db63879c994d40aebc8acdcbd6b0fdf3e013faf Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Mon, 3 Aug 2026 18:01:09 +0000 Subject: [PATCH] docs: document non-root container user for cloud agents Cloud agents now run as a dedicated non-root 'agent' user (UID/GID 1000) with passwordless sudo when the environment image doesn't set a USER. Adds a 'Container user and permissions' section to the environments page, a permission-denied entry under common issues, and a cloud agent FAQ. Co-Authored-By: Oz --- src/content/docs/platform/environments.mdx | 26 +++++++++++++++++++++- src/content/docs/platform/faqs.mdx | 4 ++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/src/content/docs/platform/environments.mdx b/src/content/docs/platform/environments.mdx index 3c1bfb65..95ae86df 100644 --- a/src/content/docs/platform/environments.mdx +++ b/src/content/docs/platform/environments.mdx @@ -35,7 +35,7 @@ An environment typically includes: * **Docker image (required)** – The task/workspace image with the toolchain and dependencies your code needs. For self-hosted Kubernetes workers, a [`default_image`](/platform/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). +* **Setup commands** – Commands to prepare the workspace (e.g., dependency install, builds, bootstrapping). Setup commands run as the [container user](#container-user-and-permissions), so prefix commands that need root access with `sudo`. 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). @@ -99,6 +99,28 @@ This process ensures every run starts from the same baseline, making results rep --- +## Container user and permissions + +Cloud agents run as a non-root user inside the container. Running without root privileges by default improves the security of agent environments. + +Warp determines the user when the container starts: + +* **Your image sets a non-root `USER`** – Warp respects the `USER` directive in your Dockerfile and runs the agent as that user, unchanged. +* **Your image starts as root (no `USER` directive)** – Warp runs the agent as a dedicated `agent` user (UID/GID 1000 where available) with passwordless `sudo` instead of running as root. +* **The image can't support a non-root user** – If `sudo` can't be installed or the workspace isn't writable by the agent user, the agent logs a warning and keeps running as root, so runs don't fail at startup. + +When your image starts as root, design the image and setup commands with the `agent` user in mind: + +* **Prefix commands that need root with `sudo`** – Commands that require root access (`apt-get install`, writing to `/usr/local` or `/etc`, `chown`, etc.) fail without a `sudo` prefix. Passwordless sudo is preconfigured and preserves your `PATH`, though sudo still strips a small set of variables it treats as unsafe (for example, `LD_*` and `BASH_ENV`). +* **Install tools outside of `/root`** – The agent's home directory is `/home/agent`, so tools or configuration stored only in root's home directory (`~/.bashrc`, `~/.cargo`, `~/.nvm`, etc.) aren't picked up. Install these system-wide or somewhere the `agent` user can access. +* **Keep directories writable by UID/GID 1000** – Files the agent creates are owned by UID 1000, and any directories baked into your image that the agent writes to must be writable by UID/GID 1000. + +:::note +Cloud agents previously ran as root. To temporarily restore that behavior while you update your image or setup commands, set the environment variable `WARP_AGENT_NONROOT=0` in your image (for example, with an `ENV` directive in your Dockerfile). This opt-out is available for a limited deprecation window after the change ships. +::: + +--- + ## When to use environments Use an environment when your run needs a predictable toolchain and repeatable setup, regardless of where it’s triggered from. @@ -303,6 +325,8 @@ If your setup commands depend on secrets or credentials, configure them through * **Setup assumes previous state** – Steps that rely on leftover caches, existing directories, or already-cloned repos can make runs unreliable. Setup failures can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). * Solution: Write idempotent setup commands that work on a fresh container. +* **Permission denied during setup commands or agent runs** – Commands fail with `Permission denied` (or `EACCES`) because the agent runs as a non-root user by default. + * Solution: Prefix commands that need root access with `sudo`, and make sure directories baked into your image are writable by UID/GID 1000. See [Container user and permissions](#container-user-and-permissions). * **Missing credentials or secrets** – Builds fail when private repos, package registries, or external services require authorization. * Solution: Configure credentials with [Agent Secrets](/platform/secrets/). * **Repo access and GitHub authorization issues** – Runs fail when GitHub doesn't have repo access or the triggering user lacks permissions. Missing external authorization can surface as [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). diff --git a/src/content/docs/platform/faqs.mdx b/src/content/docs/platform/faqs.mdx index 2231ad84..6cd568a9 100644 --- a/src/content/docs/platform/faqs.mdx +++ b/src/content/docs/platform/faqs.mdx @@ -53,6 +53,10 @@ Yes. [Codebase Context](/agents/capabilities/codebase-context/) is enabled for a Yes. Cloud agent runs execute in a full Linux environment and behave like a local development session. You can install dependencies, run Docker, and use headless tools like Playwright, subject to standard sandbox resource limits. +### Do cloud agents run as root inside the container? + +No. By default, cloud agents run as a dedicated non-root `agent` user (UID/GID 1000 where available) with passwordless sudo. If your environment's image sets a non-root `USER`, Warp runs the agent as that user instead. Commands that need root access, like `apt-get install`, work with a `sudo` prefix. See [Container user and permissions](/platform/environments/#container-user-and-permissions) for details on home directory location, file ownership, and fallback behavior. + ### Do cloud agents support a fully self-hosted, on-prem, or offline mode? The cloud agents platform supports self-hosting the **agent sandbox** (the execution environment) on your own infrastructure. The **control plane**—which handles orchestration, tracking, and auditability—remains Warp-managed and is not self-hosted.