Cloud agent environments

Environments 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.

What an environment includes

• Docker image - The image that provides the toolchain and dependencies for your code. A self-hosted Kubernetes worker with a default_image 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.

Warp provides prebuilt dev images with common languages and tools. You can also use an official image or publish your own.

How environments fit into cloud agent runs

The Automation Platform uses an environment when it starts a cloud agent run. The environment supplies the workspace and toolchain. A host supplies the compute that runs it.

• Host - Determines where the run executes. Choose Warp-hosted infrastructure or self-hosted runners.
• Agent Profiles - Set the agent’s permissions, model choice, and defaults. See Agent Profiles.
• Rules - Provide instructions that guide agent responses and decisions. See Rules.
• MCP servers - Connect agents to external tools and data. See MCP servers.
• 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.

• 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.

Related pages

• Configuring cloud agent environments to create, configure, and manage environments.
• Troubleshooting cloud agent environments to fix setup, authorization, permissions, and image failures.
• Runners to configure the compute that hosts environments.
• Deployment patterns to choose between Warp-hosted and self-hosted execution.