> For the complete documentation index, see [llms.txt](https://docs.warp.dev/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Cloud agent environments

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

Environments describe *how* an agent executes a task, not *what* it does. They give cloud agents the same container image, 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 repositories and workspace by default. You don’t need to create a standalone environment to start a factory. Configure its compute and setup through [runners](https://docs.warp.dev/factories/runners/).

An existing environment is an optional override. Set `agentDefaults.environmentId` in a [factory definition](https://docs.warp.dev/factories/factory-as-code/#agentdefaultsenvironmentid) when factory agents need that environment’s configuration. Standalone cloud workflows can create and select environments independently of a factory.

## 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://docs.warp.dev/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 [factory secrets](https://docs.warp.dev/factories/secrets/) separately; standalone workflows use [Agent Secrets](https://docs.warp.dev/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://docs.warp.dev/factories/warp-hosting/) infrastructure or [self-hosted](https://docs.warp.dev/factories/self-hosting/) runners.
-   **Agent Profiles** - Set permissions, model choice, and defaults for the Warp Agent harness. See [Agent Profiles](https://docs.warp.dev/agents/capabilities/agent-profiles-permissions/).
-   **Rules** - Provide instructions that guide agent responses and decisions. See [Rules](https://docs.warp.dev/agents/capabilities/rules/).
-   **MCP servers** - Connect agents to external tools and data. See [Connecting MCP servers to agents](https://docs.warp.dev/factories/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 existing environment when a factory needs a shared runtime override, or a standalone cloud workflow needs a predictable toolchain. For example:

-   **Integrations and schedules** - Standalone runs from integrations or a schedule can reuse the same workspace configuration. Factory automations use the factory-managed workspace unless you select an existing environment.
-   **CI and remote automation** - Reuse an environment to keep the image, repositories, and setup consistent across runs.
-   **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.

## Container users and permissions

Linux container runs use a non-root user by default. See [configuring container users](https://docs.warp.dev/factories/environments/configuring-environments/#configure-container-users) for image, setup-command, and migration requirements.

## Related pages

-   [Configuring cloud agent environments](https://docs.warp.dev/factories/environments/configuring-environments/) - Create, configure, and manage environments
-   [Troubleshooting cloud agent environments](https://docs.warp.dev/factories/environments/troubleshooting-environments/) - Fix setup, authorization, permissions, and image failures
-   [Runners](https://docs.warp.dev/factories/runners/) - Configure the compute that hosts environments
-   [Scheduled agents](https://docs.warp.dev/platform/triggers/scheduled-agents/) - Run cloud agents on a recurring cadence in a shared environment
-   [Deployment patterns](https://docs.warp.dev/factories/deployment-patterns/) - Choose between Warp-hosted and self-hosted execution