Skip to content
Warp

Factories > Environments

Cloud agent environments

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

Open in ChatGPT ↗
Ask ChatGPT about this page
Open in Claude ↗
Ask Claude about this page
Copied!

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.

An existing environment is an optional override. Set agentDefaults.environmentId in a factory definition when factory agents need that environment’s configuration. Standalone cloud workflows can create and select environments independently of a factory.

What an environment includes

Section titled “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 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 separately; standalone workflows use Agent Secrets.

Together, these settings create a fresh workspace for each run. 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

Section titled “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 infrastructure or self-hosted runners.
  • Agent Profiles - Set permissions, model choice, and defaults for the Warp Agent harness. See Agent Profiles.
  • Rules - Provide instructions that guide agent responses and decisions. See Rules.
  • MCP servers - Connect agents to external tools and data. See Connecting MCP servers to agents.
  • Per-run context - Supplies task-specific data, such as a Slack thread, PR metadata, or CI logs.

When to use an environment

Section titled “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

Section titled “Container users and permissions”

Linux container runs use a non-root user by default. See configuring container users for image, setup-command, and migration requirements.

Section titled “Related pages”