# Cloud agent environments

> Environments give cloud agents a repeatable container, repositories, and setup for every cloud agent run.

- 网址：https://funcoding.ai/agents/warp/platform/environments/
- 来源：Warp 官方文档原文（英文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.warp.dev/platform/environments/

---
Environments describe _how_ an agent executes a task, not _what_ it does. They give cloud agents the same container, repositories, and setup every time they run. Use an environment for a cloud agent run that needs a repeatable toolchain. Interactive local runs use your current checkout and machine setup, so they don't need one.

Factories manage their own repositories and workspace by default. Set `agentDefaults.environmentId` in a [factory definition](https://funcoding.ai/agents/warp/factories/factory-as-code/#agentdefaultsenvironmentid) when a factory agent must use an existing environment.

## What an environment includes

An environment groups the runtime configuration for a cloud agent run:

* **Docker image** - The image that provides the toolchain and dependencies for your code. A self-hosted Kubernetes worker with a [`default_image`](https://funcoding.ai/agents/warp/factories/self-hosting/managed-kubernetes/) can run without a separate environment.
* **Repositories** - One or more repos that the agent clones into its workspace.
* **Setup commands** - Commands that prepare the workspace, such as dependency installation, builds, or code generation.
* **Environment variables** - Runtime values that you set in the Docker image or container configuration.
* **Agent Secrets** - Credentials and sensitive values that Warp injects at runtime. Configure them separately with [Agent Secrets](https://funcoding.ai/agents/warp/platform/secrets/).

Together, these settings create a fresh workspace for each run. Warp provides [prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments) with common languages and tools. You can also use an official image or publish your own.

## How environments fit into cloud agent runs

When the Automation Platform starts a cloud agent run, it combines the environment with a host, an agent profile, and task-specific context. Each part serves a distinct purpose:

* **Host** - Determines where the run executes. Choose [Warp-hosted](https://funcoding.ai/agents/warp/factories/warp-hosting/) infrastructure or [self-hosted](https://funcoding.ai/agents/warp/factories/self-hosting/) runners.
* **Agent Profiles** - Set the agent's permissions, model choice, and defaults. See [Agent Profiles](https://funcoding.ai/agents/warp/agents/capabilities/agent-profiles-permissions/).
* **Rules** - Provide instructions that guide agent responses and decisions. See [Rules](https://funcoding.ai/agents/warp/agents/capabilities/rules/).
* **MCP servers** - Connect agents to external tools and data. See [MCP servers](https://funcoding.ai/agents/warp/platform/mcp/).
* **Per-run context** - Supplies task-specific data, such as a Slack thread, PR metadata, or CI logs.

## When to use an environment

Use an environment when your run needs a predictable toolchain and repeatable setup. This is common in the following cases:

* **Integrations and schedules** - Runs from Slack, Linear, GitHub Actions, or a schedule need the same workspace each time.
* **CI and remote automation** - An environment prevents different runners or base images from changing the result.
* **Team workflows** - A shared environment gives every teammate the same image, repos, and setup commands.
* **Toolchain-specific work** - Use an environment when the workflow depends on particular language versions, linters, build tools, or system packages.

You can skip an environment for an interactive local run in a working checkout. The local agent uses your existing machine setup.

<a id="container-user-and-permissions"></a>

## Container users and permissions

Cloud agents run as a non-root user inside the container. See [configuring container users](https://funcoding.ai/agents/warp/platform/environments/configuring-environments/#configure-container-users) for image, setup-command, and migration requirements.

## Related pages

* [Configuring cloud agent environments](https://funcoding.ai/agents/warp/platform/environments/configuring-environments/) to create, configure, and manage environments.
* [Troubleshooting cloud agent environments](https://funcoding.ai/agents/warp/platform/environments/troubleshooting-environments/) to fix setup, authorization, permissions, and image failures.
* [Runners](https://funcoding.ai/agents/warp/factories/runners/) to configure the compute that hosts environments.
* [Scheduled agents](https://funcoding.ai/agents/warp/platform/triggers/scheduled-agents/) to run cloud agents on a recurring cadence in a shared environment.
* [Deployment patterns](https://funcoding.ai/agents/warp/factories/deployment-patterns/) to choose between Warp-hosted and self-hosted execution.