docs: document non-root container user for cloud agents - #464
docs: document non-root container user for cloud agents#464hongyi-chen wants to merge 3 commits into
Conversation
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 <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
| * **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. |
There was a problem hiding this comment.
unsure if we want to have this callout, but might be worth if we had a lot of users that may be affected by this
There was a problem hiding this comment.
i think it's worth keeping. we can probably keep the opt-out around, we don't need to say we're going to deprecate it
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR documents the upcoming change for cloud agents to run as a non-root container user and adds related migration guidance in the environments page and FAQ. The structure and links fit the existing docs, and I found no security-specific findings or spec drift because no approved spec context was provided.
Concerns
- The
sudoguidance is broad enough to imply every non-root container user gets working passwordless sudo, but the new docs also say images that set a non-rootUSERrun as that user unchanged. Scope thesudoadvice to the defaultagentuser path, or explicitly state that custom non-root images must provide their own sudo behavior.
Verdict
Found: 0 critical, 2 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| * **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`. |
There was a problem hiding this comment.
sudo, but custom images that set a non-root USER are later described as running unchanged; those users may not have passwordless sudo unless their image provides it. Scope this guidance to the default agent user path.
| * **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`. | |
| * **Setup commands** – Commands to prepare the workspace (e.g., dependency install, builds, bootstrapping). Setup commands run as the [container user](#container-user-and-permissions). When Warp creates the default `agent` user for an image that starts as root, prefix commands that need root access with `sudo`. |
|
|
||
| ### 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. |
There was a problem hiding this comment.
USER case, so readers can interpret it as saying sudo always works even when Warp runs their image-defined non-root user unchanged. Limit the sudo guarantee to images where Warp creates the default agent user.
| 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. | |
| 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, unchanged. For images that start as root, 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. |
danielpeng2
left a comment
danielpeng2
left a comment
There was a problem hiding this comment.
are you planning on merging this now or when the changes actually roll out to prod?
2 participants
What
Documents the upcoming breaking change where cloud agents run as a dedicated non-root
agentuser (UID/GID 1000 where available) with passwordless sudo, instead of running as root. This is the durable docs page the customer email can link out to, per the rollout thread.platform/environments.mdx— New Container user and permissions section covering:USERdirective respected;agentuser when the image starts as root; root fallback with a warning when the image can't support a non-root user)sudoprefix for root-only commands (PATH preserved,LD_*/BASH_ENVstripped),/home/agenthome directory vs/root, UID/GID 1000 file ownership/writabilityWARP_AGENT_NONROOT=0opt-out during the deprecation windowplatform/faqs.mdx— New Q&A: "Do cloud agents run as root inside the container?" under Architecture and executionNotes for reviewers
WARP_AGENT_NONROOT=0opt-out) intentionally omits hard dates since the deprecation window end date is still TBD in the email copy; remove that note entirely once the window closes.npm run buildpasses (355 pages).Conversation: https://staging.warp.dev/conversation/109b7dd3-0781-4a4e-846d-9b3bddd3e72c
Run: https://oz.staging.warp.dev/runs/019fc8c4-ef02-755f-9e12-fe157118faf5
This PR was generated with Oz.